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

package/README.md

@@ -35,7 +35,12 @@ For agent-friendly repos, install the Vizzly skill and add a short project
 vizzly init --agent-guidance
 ```
 
-Use `vizzly init --agent-skill` to install only the local skill, or
+This installs the portable Agent Skills bundle in `.agents/skills/vizzly` and
+adds a small managed block to `AGENTS.md`. Run the same command again after a
+CLI upgrade to refresh both without replacing the rest of `AGENTS.md` or an
+existing Vizzly config.
+
+Use `vizzly init --agent-skill` to install or refresh only the local skill, or
 `vizzly init --skip-agent-skill` when you want config without the agent prompt.
 
 ### Start Local TDD
@@ -202,8 +207,8 @@ 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:
+To teach project agents the Vizzly evidence workflow, add the repo-local skill
+and AGENTS.md guidance:
 
 ```bash
 vizzly init --agent-guidance

package/dist/api/endpoints.js

@@ -38,7 +38,7 @@ export async function getBuild(client, buildId, include = null) {
  *
  * @param {Object} client - API client
  * @param {string} buildId - Build ID
- * @returns {Promise<Object>} Canonical build status bundle
+ * @returns {Promise<Object>} Build status response
  */
 export async function getBuildStatus(client, buildId) {
   return client.request(`/api/sdk/builds/${buildId}/status`);
@@ -343,51 +343,6 @@ export async function searchComparisons(client, name, filters = {}) {
   return client.request(endpoint);
 }
 
-// ============================================================================
-// Hotspot Endpoints
-// ============================================================================
-
-/**
- * Get hotspot analysis for a single screenshot
- * @param {Object} client - API client
- * @param {string} screenshotName - Screenshot name
- * @param {Object} options - Optional settings
- * @returns {Promise<Object>} Hotspot analysis data
- */
-export async function getScreenshotHotspots(client, screenshotName, options = {}) {
-  let {
-    windowSize = 20
-  } = options;
-  let encodedName = encodeURIComponent(screenshotName);
-  let endpoint = buildEndpointWithParams(`/api/sdk/screenshots/${encodedName}/hotspots`, {
-    windowSize: String(windowSize)
-  });
-  return client.request(endpoint);
-}
-
-/**
- * Batch get hotspot analysis for multiple screenshots
- * @param {Object} client - API client
- * @param {string[]} screenshotNames - Array of screenshot names
- * @param {Object} options - Optional settings
- * @returns {Promise<Object>} Hotspots keyed by screenshot name
- */
-export async function getBatchHotspots(client, screenshotNames, options = {}) {
-  let {
-    windowSize = 20
-  } = options;
-  return client.request('/api/sdk/screenshots/hotspots', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({
-      screenshot_names: screenshotNames,
-      windowSize
-    })
-  });
-}
-
 // ============================================================================
 // Auth/Token Endpoints
 // ============================================================================

package/dist/api/index.js

@@ -16,4 +16,4 @@ export { createApiClient, DEFAULT_API_URL } from './client.js';
 export { buildApiUrl, buildAuthHeader, buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildRequestHeaders, buildScreenshotCheckObject, buildScreenshotPayload, buildScreenshotResolvePayload, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.js';
 
 // Endpoint functions
-export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuildContext, getBuildStatus, getBuilds, getComparison, getComparisonContext, getPreviewInfo, getReviewQueueContext, getScreenshotContext, getScreenshotHotspots, getSimilarFingerprintContext, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';
+export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBuild, getBuildContext, getBuildStatus, getBuilds, getComparison, getComparisonContext, getPreviewInfo, getReviewQueueContext, getScreenshotContext, getSimilarFingerprintContext, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadPreviewZip, uploadScreenshot } from './endpoints.js';

package/dist/cli.js

@@ -450,7 +450,7 @@ try {
 } catch (error) {
   output.debug(`Plugin loading failed: ${error.message}`);
 }
-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 => {
+program.command('init').description('Initialize Vizzly in your project').option('--force', 'Overwrite existing configuration').option('--agent-skill', 'Install or refresh the repo-local Vizzly agent skill').option('--agent-guidance', 'Install or refresh the repo-local Vizzly skill and AGENTS.md guidance').option('--skip-agent-skill', 'Skip the Vizzly agent skill prompt').action(async options => {
   let globalOptions = getGlobalOptions();
   await init({
     ...globalOptions,
@@ -681,7 +681,7 @@ Examples:
   }
   await contextComparisonCommand(comparisonId, options, globalOptions);
 });
-contextCmd.command('screenshot').description('Fetch screenshot context and historical memory').argument('<name>', 'Screenshot name').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--recent-limit <n>', 'Maximum recent comparisons to return (1-50)', Number).option('--window-size <n>', 'Historical hotspot analysis window size (1-50)', Number).addHelpText('after', `
+contextCmd.command('screenshot').description('Fetch screenshot context and historical memory').argument('<name>', 'Screenshot name').option('--source <source>', 'Context source: auto, cloud, or local', 'auto').option('-p, --project <slug-or-id>', 'Project scope for user auth lookups').option('--org <slug>', 'Organization slug when project slug is ambiguous').option('--recent-limit <n>', 'Maximum recent comparisons to return (1-50)', Number).addHelpText('after', `
 Examples:
   $ vizzly context screenshot Dashboard --source cloud
   $ vizzly context screenshot Dashboard --source local
@@ -738,15 +738,15 @@ Note: Baselines are stored locally in .vizzly/baselines/ during TDD mode.
   let globalOptions = getGlobalOptions();
   await baselinesCommand(options, globalOptions);
 });
-program.command('api').description('Make raw API requests (for power users)').argument('<endpoint>', 'API endpoint (e.g., /api/sdk/builds)').option('-X, --method <method>', 'HTTP method (GET or POST for approve/reject/comment)', 'GET').option('-d, --data <json>', 'Request body (JSON)').option('-H, --header <header>', 'Add header (key:value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).option('-q, --query <param>', 'Add query param (key=value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).addHelpText('after', `
+program.command('api').description('Make raw API requests (for power users)').argument('<endpoint>', 'API endpoint (e.g., /api/sdk/builds)').option('-X, --method <method>', 'HTTP method (GET or POST for build comments)', 'GET').option('-d, --data <json>', 'Request body (JSON)').option('-H, --header <header>', 'Add header (key:value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).option('-q, --query <param>', 'Add query param (key=value), can be repeated', (val, prev) => prev ? [...prev, val] : [val]).addHelpText('after', `
 Examples:
   $ vizzly api /api/sdk/builds                    # List builds
   $ vizzly api /api/sdk/builds -q limit=5         # With query params
   $ vizzly api /api/sdk/builds/abc123             # Get specific build
-  $ vizzly api /api/sdk/comparisons/abc123/approve -X POST
+  $ vizzly api /api/sdk/builds/abc123/comments -X POST -d '{"content":"Looks good"}'
   $ vizzly api /api/sdk/builds/abc123/comments -X POST -d '{"content":"Nice!"}'
 
-Note: POST is restricted to approve, reject, and comment endpoints.
+Note: POST is restricted to build comment endpoints. Use dedicated approve/reject commands for review decisions.
 Most operations have dedicated commands (builds, comparisons, approve, etc.).
 `).action(async (endpoint, options) => {
   let globalOptions = getGlobalOptions();

package/dist/commands/api.js

@@ -5,7 +5,7 @@
 import { createApiClient as defaultCreateApiClient } from '../api/index.js';
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
-let ALLOWED_POST_ENDPOINTS = [/^\/api\/sdk\/comparisons\/[^/]+\/approve$/, /^\/api\/sdk\/comparisons\/[^/]+\/reject$/, /^\/api\/sdk\/builds\/[^/]+\/comments$/];
+let ALLOWED_POST_ENDPOINTS = [/^\/api\/sdk\/builds\/[^/]+\/comments$/];
 function createApiCommandDeps(deps = {}) {
   return {
     loadConfig: deps.loadConfig || defaultLoadConfig,
@@ -70,11 +70,11 @@ export function validateApiRequest({
 }) {
   let errors = [];
   if (method !== 'GET' && method !== 'POST') {
-    errors.push(`Method ${method} not allowed. Use GET for queries or POST for approve/reject/comment.`);
+    errors.push(`Method ${method} not allowed. Use GET for queries or POST for build comments.`);
     return errors;
   }
   if (method === 'POST' && !isAllowedPostEndpoint(endpoint)) {
-    errors.push(`POST not allowed for ${endpoint}. Only approve, reject, and comment endpoints support POST.`);
+    errors.push(`POST not allowed for ${endpoint}. Only build comment endpoints support POST.`);
   }
   if (hasData && method !== 'POST') {
     errors.push('Request data requires --method POST.');

package/dist/commands/builds.js

@@ -112,13 +112,11 @@ export async function buildsCommand(options = {}, globalOptions = {}, deps = {})
     for (let build of builds) {
       let statusColor = getStatusColor(colors, build.status);
       let statusBadge = statusColor(build.status.toUpperCase());
-
-      // Approval badge
-      let approvalBadge = '';
-      if (build.approval_status && build.status === 'completed') {
-        approvalBadge = ` ${getApprovalBadge(colors, build.approval_status)}`;
+      let reviewBadge = '';
+      if (build.visual_review?.state && build.status === 'completed') {
+        reviewBadge = ` ${getReviewBadge(colors, build.visual_review.state)}`;
       }
-      output.print(`  ${colors.bold(build.name || build.id)} ${statusBadge}${approvalBadge}`);
+      output.print(`  ${colors.bold(build.name || build.id)} ${statusBadge}${reviewBadge}`);
       let details = [];
       if (build.branch) details.push(build.branch);
       if (build.commit_sha) details.push(build.commit_sha.substring(0, 7));
@@ -174,7 +172,7 @@ function formatBuildForJson(build, includeComparisons = false) {
       changed: build.changed_comparisons || 0,
       identical: build.identical_comparisons || 0
     },
-    approvalStatus: build.approval_status,
+    visual_review: build.visual_review || null,
     createdAt: build.created_at,
     completedAt: build.completed_at
   };
@@ -192,7 +190,7 @@ function formatBuildForJson(build, includeComparisons = false) {
         name: c.name || c.current_name,
         status: c.status,
         diffPercentage: c.diff_percentage,
-        approvalStatus: c.approval_status,
+        visual_review: c.visual_review || null,
         urls: {
           baseline: c.baseline_screenshot?.original_url || c.baseline_original_url || c.baseline_screenshot_url || null,
           current: c.current_screenshot?.original_url || c.current_original_url || c.current_screenshot_url || null,
@@ -238,8 +236,8 @@ function displayBuild(output, build, verbose) {
   if (stats.length > 0) {
     output.labelValue('Comparisons', stats.join(colors.dim(' · ')));
   }
-  if (build.approval_status) {
-    output.labelValue('Approval', build.approval_status);
+  if (build.visual_review?.state) {
+    output.labelValue('Review', build.visual_review.state);
   }
   output.blank();
   if (build.created_at) {
@@ -290,19 +288,18 @@ function getStatusColor(colors, status) {
 }
 
 /**
- * Get colored approval badge
+ * Get colored review badge
  */
-function getApprovalBadge(colors, approvalStatus) {
-  switch (approvalStatus) {
+function getReviewBadge(colors, reviewState) {
+  switch (reviewState) {
     case 'approved':
-    case 'auto_approved':
       return colors.brand.success('APPROVED');
     case 'rejected':
       return colors.brand.error('REJECTED');
     case 'pending':
       return colors.brand.warning('PENDING');
     default:
-      return colors.dim(approvalStatus?.toUpperCase() || '');
+      return colors.dim(reviewState?.toUpperCase() || '');
   }
 }
 

package/dist/commands/comparisons.js

@@ -6,7 +6,7 @@ import { createApiClient as defaultCreateApiClient, getBuild as defaultGetBuild,
 import { loadConfig as defaultLoadConfig } from '../utils/config-loader.js';
 import * as defaultOutput from '../utils/output.js';
 import { createWildcardMatcher } from '../utils/patterns.js';
-import { getComparisonBrowser, getComparisonName, getComparisonResult, getComparisonViewport, getVisualReviewState } from '../utils/visual-context-normalizers.js';
+import { getComparisonBrowser, getComparisonName, getComparisonResult, getComparisonViewport } from '../utils/visual-context-normalizers.js';
 
 /**
  * Comparisons command - query comparisons with various filters
@@ -165,19 +165,17 @@ function formatComparisonForJson(comparison) {
   let ssimScore = comparison.ssim_score ?? diffImage.ssim_score ?? null;
   let gmsdScore = comparison.gmsd_score ?? diffImage.gmsd_score ?? null;
   let fingerprintHash = comparison.fingerprint_hash || diffImage.fingerprint_hash || null;
-  let projection = comparison.analysis_projection || comparison.projection || diffImage.analysis_projection || diffImage.projection || null;
+  let analysisDetails = comparison.analysis_details || diffImage.analysis_details || null;
   let diffRegions = comparison.diff_regions ?? diffImage.diff_regions ?? null;
-  let regionCount = comparison.region_count ?? diffImage.region_count ?? projection?.clusters?.count ?? (Array.isArray(diffRegions) ? diffRegions.length : null);
-  let hasHoneydiff = clusterMetadata || ssimScore != null || gmsdScore != null || fingerprintHash || projection || regionCount != null;
+  let regionCount = comparison.region_count ?? diffImage.region_count ?? analysisDetails?.clusters?.count ?? (Array.isArray(diffRegions) ? diffRegions.length : null);
+  let hasHoneydiff = clusterMetadata || ssimScore != null || gmsdScore != null || fingerprintHash || analysisDetails || regionCount != null;
   return {
     id: comparison.id,
     name: getComparisonName(comparison),
     status: comparison.status,
     result: getComparisonResult(comparison),
     diffPercentage: comparison.diff_percentage ?? null,
-    approvalStatus: comparison.approval_status,
-    reviewState: getVisualReviewState(comparison),
-    visualReview: comparison.visual_review || null,
+    visual_review: comparison.visual_review || null,
     viewport: getComparisonViewport(comparison),
     browser: getComparisonBrowser(comparison),
     urls: {
@@ -192,7 +190,7 @@ function formatComparisonForJson(comparison) {
       clusterMetadata,
       fingerprintHash,
       regionCount,
-      projection,
+      details: analysisDetails,
       diffRegions,
       diffLines: comparison.diff_lines ?? diffImage.diff_lines ?? null,
       fingerprintData: comparison.fingerprint_data ?? diffImage.fingerprint_data ?? null
@@ -214,7 +212,7 @@ function displayComparison(output, comparison, verbose) {
     Name: formatted.name,
     Status: formatted.result?.toUpperCase(),
     'Diff %': comparison.diff_percentage != null ? `${(comparison.diff_percentage * 100).toFixed(2)}%` : 'N/A',
-    Review: formatted.reviewState || 'unknown'
+    Review: formatted.visual_review?.state || 'unknown'
   });
   output.blank();
   if (formatted.viewport) {

package/dist/commands/context.js

@@ -393,7 +393,7 @@ function buildCompactBuildCommands(context = {}, include = [], cursor = null) {
       command: appendContextSource(`vizzly --json context screenshot ${quoteCommandArgument(screenshotName)}`, context)
     });
   }
-  if (buildTarget && evidence.length > 0) {
+  if (buildTarget && evidence.length > 0 && !include.includes('diffs')) {
     let cursorFlag = cursor ? ` --cursor ${quoteCommandArgument(cursor)}` : '';
     commands.push({
       label: 'Load raw diff diagnostics',
@@ -427,6 +427,12 @@ function buildCompactComparisonCommands(context = {}, include = []) {
   let comparisonId = context.comparison?.id;
   let streams = [['similar_by_fingerprint', 'similar history'], ['recent_by_name', 'recent history']];
   let includeFlag = include.length > 0 ? ` --include ${include.join(',')}` : '';
+  if (comparisonId && !include.includes('diffs')) {
+    commands.push({
+      label: 'Load raw diff diagnostics',
+      command: appendContextSource(`vizzly --json context comparison ${quoteCommandArgument(comparisonId)} --agent --include diffs`, context)
+    });
+  }
   for (let [stream, label] of streams) {
     let page = context.history?.[stream]?.page;
     if (!comparisonId || !page?.has_more || !page.next_cursor) {
@@ -565,9 +571,6 @@ function formatNeedsReview(status = {}) {
   }
   return details.length > 0 ? `yes · ${details.join(' · ')}` : 'yes';
 }
-function formatConfirmedRegionLabels(regions = []) {
-  return regions.map(region => region.label).filter(Boolean).slice(0, 3).join(' · ');
-}
 function printComparisonList(output, comparisons = [], {
   limit = 5
 } = {}) {
@@ -735,19 +738,15 @@ function displayComparisonContext(output, context) {
   let statusTone = getStatusTone(colors, displayState);
   let screenshotName = context.comparison.screenshot?.name || context.comparison.id;
   let analysis = context.comparison.analysis || {};
-  let confirmedRegionLabels = formatConfirmedRegionLabels(context.history.confirmed_regions);
   output.print(`  ${colors.bold(screenshotName)} ${statusTone(displayState.toUpperCase())}`);
   output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
   output.blank();
   output.labelValue('Eyes', `${analysis.diff_image_url ? 'baseline/current/diff' : 'comparison metadata only'}`);
-  output.labelValue('Memory', `${context.history.similar_by_fingerprint.length} similar · ${context.history.recent_by_name.length} recent · ${context.history.confirmed_regions.length} confirmed regions`);
+  output.labelValue('Memory', `${context.history.similar_by_fingerprint.length} similar · ${context.history.recent_by_name.length} recent`);
   output.labelValue('Review', `${context.review.build_comments.length} build comments · ${countScreenshotCommentEntries(context.review.screenshot_comments)} screenshot comments`);
   if (analysis.fingerprint_hash) {
     output.labelValue('Fingerprint', analysis.fingerprint_hash);
   }
-  if (confirmedRegionLabels) {
-    output.labelValue('Known Regions', confirmedRegionLabels);
-  }
   if (context.links?.comparison_url) {
     output.labelValue('Comparison URL', context.links.comparison_url);
   }
@@ -760,15 +759,10 @@ function displayComparisonContext(output, context) {
 function displayScreenshotContext(output, context) {
   output.header('context', 'screenshot');
   let colors = output.getColors();
-  let confirmedRegionLabels = formatConfirmedRegionLabels(context.confirmed_regions);
   output.print(`  ${colors.bold(context.screenshot.name)}`);
   output.print(`  ${colors.dim(`@${context.scope.organization.slug}/${context.scope.project.slug}`)}`);
   output.blank();
-  output.labelValue('Memory', `${context.history.recent_comparisons.length} recent comparisons · ${context.confirmed_regions.length} confirmed regions`);
-  output.labelValue('Hotspots', `${context.hotspot_analysis.total_builds_analyzed} builds analyzed · ${context.hotspot_analysis.confidence}`);
-  if (confirmedRegionLabels) {
-    output.labelValue('Known Regions', confirmedRegionLabels);
-  }
+  output.labelValue('Memory', `${context.history.recent_comparisons.length} recent comparisons`);
   if (context.history.recent_comparisons.length > 0) {
     output.blank();
     output.print('  Recent Comparisons');
@@ -934,8 +928,7 @@ export async function contextScreenshotCommand(screenshotName, options = {}, glo
       return;
     }
     let query = buildScopeQuery(options, {
-      recentLimit: options.recentLimit,
-      windowSize: options.windowSize
+      recentLimit: options.recentLimit
     });
     output.startSpinner('Fetching screenshot context...');
     let context = await runtime.provider.getScreenshotContext(screenshotName, query);
@@ -1052,9 +1045,6 @@ export function validateContextScreenshotOptions(options = {}) {
   errors.push(...validateLimitRange(options.recentLimit, '--recent-limit', {
     max: 50
   }));
-  errors.push(...validateLimitRange(options.windowSize, '--window-size', {
-    max: 50
-  }));
   return errors;
 }
 export function validateContextSimilarOptions(options = {}) {

package/dist/commands/init.js

@@ -23,6 +23,7 @@ function createInitDeps(deps = {}) {
     output: deps.output || output,
     promptAgentSkill: deps.promptAgentSkill || promptAgentSkill,
     readFile: deps.readFile || fs.readFile,
+    remove: deps.remove || fs.rm,
     skillSourcePath: deps.skillSourcePath || getPackagedAgentSkillPath(),
     writeFile: deps.writeFile || fs.writeFile
   };
@@ -213,16 +214,20 @@ async function shouldInstallAgentSkill(options, deps) {
 let agentGuidanceStart = '<!-- vizzly-agent-guidance -->';
 let agentGuidanceEnd = '<!-- /vizzly-agent-guidance -->';
 function createAgentGuidanceContent() {
+  let skillPath = '.agents/skills/vizzly/SKILL.md';
   return `${agentGuidanceStart}
 ## Visual Testing With Vizzly
 
-Use Vizzly for user-facing UI changes when this repo has Vizzly configured.
+For user-facing changes, use the repo-local Vizzly skill at
+\`${skillPath}\`.
 
-- 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\`
+- Inspect existing visual evidence before and after the change.
+- Use the repository's established Vizzly command and owning user workflow.
+- Read bounded JSON with \`--agent --json\`, then inspect baseline, current, and
+  diff images together.
 
-Prefer existing E2E/user journeys over narrow screenshot-only specs. Treat Vizzly diffs as review evidence; do not approve or reject changes unless asked.
+Treat Vizzly diffs as review evidence. Do not approve, reject, or replace
+evidence unless the task explicitly asks for that mutation.
 ${agentGuidanceEnd}
 `;
 }
@@ -248,9 +253,28 @@ async function upsertProjectAgentGuidance({
     };
   }
   let existingContent = await readFile(agentsPath, 'utf8');
-  if (existingContent.includes(agentGuidanceStart)) {
+  let startIndex = existingContent.indexOf(agentGuidanceStart);
+  let endIndex = existingContent.indexOf(agentGuidanceEnd);
+  let startCount = existingContent.split(agentGuidanceStart).length - 1;
+  let endCount = existingContent.split(agentGuidanceEnd).length - 1;
+  if (startCount !== endCount || startCount > 1 || startCount === 1 && endIndex < startIndex) {
     return {
-      status: 'exists',
+      status: 'malformed',
+      agentsPath
+    };
+  }
+  if (startIndex >= 0 && endIndex >= startIndex) {
+    let blockEnd = endIndex + agentGuidanceEnd.length;
+    let refreshedContent = `${existingContent.slice(0, startIndex)}${guidance.trimEnd()}${existingContent.slice(blockEnd)}`;
+    if (refreshedContent === existingContent) {
+      return {
+        status: 'exists',
+        agentsPath
+      };
+    }
+    await writeFile(agentsPath, refreshedContent, 'utf8');
+    return {
+      status: 'refreshed',
       agentsPath
     };
   }
@@ -263,9 +287,11 @@ async function upsertProjectAgentGuidance({
 export async function installProjectAgentSkill({
   cwd,
   sourcePath,
+  refresh = false,
   access = fs.access,
   copy = fs.cp,
-  mkdir = fs.mkdir
+  mkdir = fs.mkdir,
+  remove = fs.rm
 }) {
   let targetPath = getProjectAgentSkillPath(cwd);
   if (!(await fileExists(path.join(sourcePath, 'SKILL.md'), access))) {
@@ -275,7 +301,8 @@ export async function installProjectAgentSkill({
       targetPath
     };
   }
-  if (await fileExists(targetPath, access)) {
+  let targetExists = await fileExists(targetPath, access);
+  if (targetExists && !refresh) {
     return {
       status: 'exists',
       sourcePath,
@@ -287,11 +314,16 @@ export async function installProjectAgentSkill({
   });
   await copy(sourcePath, targetPath, {
     recursive: true,
-    errorOnExist: true,
-    force: false
+    errorOnExist: !targetExists,
+    force: targetExists
   });
+  if (targetExists) {
+    await remove(path.join(targetPath, 'agents', 'openai.yaml'), {
+      force: true
+    });
+  }
   return {
-    status: 'installed',
+    status: targetExists ? 'refreshed' : 'installed',
     sourcePath,
     targetPath
   };
@@ -305,6 +337,11 @@ function writeAgentSkillOutput(output, result) {
     output.hint(`Installed at ${result.targetPath}`);
     return;
   }
+  if (result.status === 'refreshed') {
+    output.complete('Refreshed Vizzly agent skill');
+    output.hint(`Updated ${result.targetPath}`);
+    return;
+  }
   if (result.status === 'exists') {
     output.hint('Vizzly agent skill already exists in this repo');
     return;
@@ -327,8 +364,18 @@ function writeAgentGuidanceOutput(output, result) {
     output.hint(`Updated ${result.agentsPath}`);
     return;
   }
+  if (result.status === 'refreshed') {
+    output.complete('Refreshed Vizzly guidance in AGENTS.md');
+    output.hint(`Updated ${result.agentsPath}`);
+    return;
+  }
   if (result.status === 'exists') {
     output.hint('Vizzly guidance already exists in AGENTS.md');
+    return;
+  }
+  if (result.status === 'malformed') {
+    output.warn('Vizzly guidance markers in AGENTS.md are incomplete');
+    output.hint(`Repair the managed block in ${result.agentsPath}`);
   }
 }
 function withAgentSetupResults(payload, {
@@ -381,7 +428,9 @@ export async function init(options = {}, deps = {}) {
       sourcePath: resolvedDeps.skillSourcePath,
       access: resolvedDeps.access,
       copy: resolvedDeps.copy,
-      mkdir: resolvedDeps.mkdir
+      mkdir: resolvedDeps.mkdir,
+      refresh: options.agentGuidance || options.agentSkill,
+      remove: resolvedDeps.remove
     });
   }
   if (options.agentGuidance) {