✨ Add CLI visual context workflows

README.md

@@ -58,6 +58,33 @@ export VIZZLY_TOKEN=your-project-token
 vizzly run "npm test" --wait
 ```
 
+### Visual Context For Agents
+
+Use `vizzly context` when you want Vizzly to act more like visual context than a test runner.
+
+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.
+
+```bash
+# Cloud context for a build or comparison
+vizzly context build abc123
+vizzly context comparison def456 --json
+
+# Local workspace context from .vizzly/
+vizzly context build current --source local
+vizzly context screenshot build-detail-screenshots --source local --json
+```
+
+`--json` is the main automation path. Human-readable output is there for quick terminal use, but
+JSON is what you want for scripts, agents, and prompt assembly.
+
+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.
+
+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.
+
 ## Capture Screenshots
 
 Add screenshots to your existing tests:
@@ -116,6 +143,7 @@ export default {
 | `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 |

docs/json-output.md

@@ -190,6 +190,166 @@ vizzly tdd list --json
 }
 ```
 
+### `vizzly context`
+
+Use `vizzly context` when you want one machine-friendly bundle instead of several narrow calls.
+This is the best fit for automation, agents, and scripts that need visual evidence plus a little
+bit of memory.
+
+Every context payload includes a `source` field. That tells you whether the bundle came from
+cloud data or your local `.vizzly` workspace.
+
+#### `vizzly context build`
+
+```bash
+vizzly context build abc123 --json
+vizzly context build current --source local --json
+```
+
+```json
+{
+  "resource": "build_context",
+  "source": "cloud",
+  "scope": {
+    "organization": { "slug": "acme" },
+    "project": { "slug": "storybook" }
+  },
+  "build": {
+    "id": "abc123",
+    "status": "completed",
+    "approval_status": "pending"
+  },
+  "summary": {
+    "comparisons": {
+      "total": 12,
+      "changed": 2,
+      "new": 1
+    },
+    "review": {
+      "pending": 3,
+      "approved": 9,
+      "rejected": 0
+    }
+  },
+  "comparisons": [
+    {
+      "id": "cmp-1",
+      "name": "Dashboard",
+      "result": "changed",
+      "diff_percentage": 0.42
+    }
+  ]
+}
+```
+
+#### `vizzly context comparison`
+
+```bash
+vizzly context comparison cmp-1 --json
+vizzly context comparison build-detail-screenshots --source local --json
+```
+
+```json
+{
+  "resource": "comparison_context",
+  "source": "local_workspace",
+  "comparison": {
+    "id": "cmp-1",
+    "name": "Dashboard",
+    "result": "changed",
+    "analysis": {
+      "diff_image_url": ".vizzly/diffs/dashboard.png",
+      "diff_regions": [],
+      "confirmed_regions": []
+    }
+  },
+  "history": {
+    "similar_by_fingerprint": [],
+    "recent_by_name": [],
+    "hotspot_analysis": {
+      "confidence": "no_data"
+    }
+  }
+}
+```
+
+#### `vizzly context screenshot`
+
+```bash
+vizzly context screenshot Dashboard --json
+vizzly context screenshot Dashboard --source local --json
+```
+
+```json
+{
+  "resource": "screenshot_context",
+  "source": "cloud",
+  "screenshot": {
+    "name": "Dashboard"
+  },
+  "confirmed_regions": [
+    {
+      "label": "Known header copy band"
+    }
+  ],
+  "history": {
+    "recent_comparisons": []
+  }
+}
+```
+
+#### `vizzly context similar`
+
+```bash
+vizzly context similar fp-dashboard --project storybook --org acme --json
+```
+
+```json
+{
+  "resource": "fingerprint_context",
+  "source": "cloud",
+  "fingerprint": {
+    "hash": "fp-dashboard"
+  },
+  "matches": [
+    {
+      "comparison_id": "cmp-1",
+      "build_id": "abc123",
+      "screenshot_name": "Dashboard"
+    }
+  ]
+}
+```
+
+Local workspace similarity is not supported yet. If you point `context similar` at `--source local`,
+the CLI returns a clear error instead of pretending the data exists.
+
+#### `vizzly context review-queue`
+
+```bash
+vizzly context review-queue --project storybook --org acme --json
+vizzly context review-queue --source local --json
+```
+
+```json
+{
+  "resource": "review_queue_context",
+  "source": "local_workspace",
+  "summary": {
+    "total": 2,
+    "changed": 1,
+    "new": 1
+  },
+  "comparisons": [
+    {
+      "id": "cmp-1",
+      "name": "Settings Panel",
+      "result": "changed"
+    }
+  ]
+}
+```
+
 ### `vizzly builds`
 
 List builds with optional filtering:

src/api/endpoints.js

@@ -225,6 +225,85 @@ export async function getComparison(client, comparisonId) {
   return response.comparison;
 }
 
+/**
+ * Get build context bundle for agent and reviewer workflows
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} Build context bundle
+ */
+export async function getBuildContext(client, buildId) {
+  return client.request(`/api/sdk/context/builds/${buildId}`);
+}
+
+/**
+ * Get comparison context bundle with similarity and history
+ * @param {Object} client - API client
+ * @param {string} comparisonId - Comparison ID
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Comparison context bundle
+ */
+export async function getComparisonContext(client, comparisonId, options = {}) {
+  let endpoint = buildEndpointWithParams(
+    `/api/sdk/context/comparisons/${comparisonId}`,
+    options
+  );
+  return client.request(endpoint);
+}
+
+/**
+ * Get screenshot context bundle for a screenshot name
+ * @param {Object} client - API client
+ * @param {string} screenshotName - Screenshot name
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Screenshot context bundle
+ */
+export async function getScreenshotContext(
+  client,
+  screenshotName,
+  options = {}
+) {
+  let encodedName = encodeURIComponent(screenshotName);
+  let endpoint = buildEndpointWithParams(
+    `/api/sdk/context/screenshots/${encodedName}`,
+    options
+  );
+  return client.request(endpoint);
+}
+
+/**
+ * Get project-scoped similar comparisons for a fingerprint hash
+ * @param {Object} client - API client
+ * @param {string} fingerprintHash - Honeydiff fingerprint hash
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Fingerprint context bundle
+ */
+export async function getSimilarFingerprintContext(
+  client,
+  fingerprintHash,
+  options = {}
+) {
+  let encodedFingerprint = encodeURIComponent(fingerprintHash);
+  let endpoint = buildEndpointWithParams(
+    `/api/sdk/context/fingerprints/${encodedFingerprint}/similar`,
+    options
+  );
+  return client.request(endpoint);
+}
+
+/**
+ * Get pending review queue context for a project
+ * @param {Object} client - API client
+ * @param {Object} options - Optional query params
+ * @returns {Promise<Object>} Review queue context bundle
+ */
+export async function getReviewQueueContext(client, options = {}) {
+  let endpoint = buildEndpointWithParams(
+    '/api/sdk/context/review-queue',
+    options
+  );
+  return client.request(endpoint);
+}
+
 /**
  * Search for comparisons by name
  * @param {Object} client - API client

src/api/index.js

@@ -43,10 +43,15 @@ export {
   finalizeParallelBuild,
   getBatchHotspots,
   getBuild,
+  getBuildContext,
   getBuilds,
   getComparison,
+  getComparisonContext,
   getPreviewInfo,
+  getReviewQueueContext,
+  getScreenshotContext,
   getScreenshotHotspots,
+  getSimilarFingerprintContext,
   getTddBaselines,
   getTokenContext,
   searchComparisons,