✨ Improve agent context drill-downs

README.md

@@ -101,7 +101,8 @@ evidence in one place.
 ```bash
 # Cloud context for a build or comparison
 vizzly context build abc123 --source cloud
-vizzly context comparison def456 --source cloud --json
+vizzly context build abc123 --source cloud --agent --json --offset 10
+vizzly context comparison def456 --source cloud --agent --json
 
 # Local workspace context from .vizzly/
 vizzly context build current --source local
@@ -110,8 +111,10 @@ 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. Add `--full` when you need the whole payload, or
+`--json` is the durable automation path. `--agent` gives a normalized handoff
+for prompt assembly. Build handoffs contain up to 10 records; use the returned
+next-page command or `--offset` to continue without loading the full build. 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`

docs/json-output.md

@@ -264,6 +264,7 @@ cloud data or your local `.vizzly` workspace.
 ```bash
 vizzly context build abc123 --source cloud --json
 vizzly context build abc123 --source cloud --agent --json
+vizzly context build abc123 --source cloud --agent --json --offset 10
 vizzly context build abc123 --source cloud --agent --json --include diffs,comments
 vizzly context build abc123 --source cloud --agent --json --full
 vizzly context build current --source local --json
@@ -273,7 +274,8 @@ vizzly context build current --source local --agent
 Use `--json` for durable automation. Use `--agent --json` when you want the compact handoff that
 agents should read first. It returns at most 10 actionable evidence records while preserving API
 order, with failed captures first and one variant from each screenshot group before additional
-variants. Add `--include diffs` for raw Honeydiff diagnostics on those selected records. Explicit
+variants. Follow the returned next-page command or use `--offset` to continue through that order.
+Add `--include diffs` for raw Honeydiff diagnostics on those selected records. Explicit
 `screenshots` and `comments` includes return those API collections, and `--full` returns the
 complete build context payload unchanged.
 
@@ -315,7 +317,10 @@ Compact agent JSON:
     }
   },
   "evidence_limit": 10,
+  "evidence_offset": 0,
+  "evidence_total": 1,
   "evidence_returned": 1,
+  "evidence_has_more": false,
   "evidence_truncated": false,
   "evidence": [
     {
@@ -359,7 +364,7 @@ Compact agent JSON:
   "suggested_commands": [
     {
       "label": "Inspect comparison context",
-      "command": "vizzly --json context comparison cmp-1 --source cloud"
+      "command": "vizzly --json context comparison cmp-1 --agent --source cloud"
     },
     {
       "label": "Inspect screenshot history",
@@ -375,9 +380,9 @@ Compact agent JSON:
 
 `status`, `summary`, review state, asset URLs, and Honeydiff values come from the API. The compact
 client does not estimate processing progress or rebuild server aggregates. Its local work is
-limited to normalization, bounded evidence selection, truncation facts, and executable
-`suggested_commands`. When `evidence_truncated` is `true`, the suggestions also include a `--full`
-command.
+limited to normalization, API-ordered evidence paging, truncation facts, and executable
+`suggested_commands`. When more records follow the current page, the suggestions include the exact
+next `--offset`. When the page omits any records, they also include a `--full` command.
 
 Full build context JSON:
 
@@ -452,9 +457,48 @@ Full build context JSON:
 
 ```bash
 vizzly context comparison cmp-1 --source cloud --json
+vizzly context comparison cmp-1 --source cloud --agent --json
 vizzly context comparison build-detail-screenshots --source local --json
 ```
 
+Raw JSON preserves the provider response. Add `--agent` to normalize current, baseline, diff, and
+Honeydiff fields into the same evidence shape used by compact build context.
+
+Agent comparison JSON:
+
+```json
+{
+  "resource": "comparison_agent_context",
+  "source": "cloud",
+  "comparison": {
+    "id": "cmp-1",
+    "name": "Dashboard",
+    "result": "changed",
+    "review_state": "pending",
+    "screenshot": {
+      "url": "https://.../current.png"
+    },
+    "baseline": {
+      "url": "https://.../baseline.png"
+    },
+    "diff": {
+      "image_url": "https://.../diff.png",
+      "fingerprint_hash": "00000000001ec127",
+      "regions": [],
+      "cluster_metadata": {
+        "classification": "dynamic_content"
+      }
+    }
+  },
+  "history": {
+    "similar_by_fingerprint": [],
+    "recent_by_name": []
+  }
+}
+```
+
+Raw comparison JSON remains available without `--agent`:
+
 ```json
 {
   "resource": "comparison_context",

skills/vizzly/references/cli-context.md

@@ -84,7 +84,7 @@ For each evidence record:
 Useful manual drill-downs are:
 
 ```bash
-vizzly context comparison <comparison-id> --source <local-or-cloud> --json
+vizzly context comparison <comparison-id> --source <local-or-cloud> --agent --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
@@ -94,3 +94,7 @@ 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.
+
+When a build has more than 10 actionable records, run its returned next-page
+command. The command uses `--offset` to preserve API order without pulling the
+full build context into the agent handoff.

src/api/client.js

@@ -27,6 +27,16 @@ function isProjectToken(token) {
   return typeof token === 'string' && token.startsWith('vzt_');
 }
 
+/** Prefer the transport cause because Node's top-level fetch message is generic. */
+function getNetworkFailureReason(error) {
+  return (
+    error?.cause?.code ||
+    error?.cause?.message ||
+    error?.message ||
+    'request failed'
+  );
+}
+
 /**
  * Create an API client with the given configuration
  *
@@ -75,10 +85,21 @@ export function createApiClient(options = {}) {
       extra: fetchOptions.headers || {},
     });
 
-    let response = await fetch(url, {
-      ...fetchOptions,
-      headers,
-    });
+    let response;
+    try {
+      response = await fetch(url, {
+        ...fetchOptions,
+        headers,
+      });
+    } catch (error) {
+      let apiOrigin = new URL(url).origin;
+      let reason = getNetworkFailureReason(error);
+      throw new VizzlyError(
+        `Unable to reach Vizzly at ${apiOrigin}: ${reason}`,
+        'NETWORK_ERROR',
+        { apiOrigin }
+      );
+    }
 
     if (!response.ok) {
       let errorBody = await extractErrorBody(response);

src/cli.js

@@ -982,6 +982,12 @@ contextCmd
   .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(
+    '--offset <n>',
+    'Skip the first N evidence records with --agent --json',
+    Number,
+    0
+  )
   .option(
     '--include <items>',
     'Add detail to compact agent JSON: screenshots,diffs,comments'
@@ -994,6 +1000,7 @@ Examples:
   $ vizzly context build current --source local
   $ vizzly context build current --source local --agent
   $ vizzly context build abc123 --source cloud --agent --json
+  $ vizzly context build abc123 --source cloud --agent --json --offset 10
   $ vizzly context build abc123 --source cloud --agent --json --include diffs,comments
   $ vizzly context build abc123 --source cloud --agent --json --full
 `
@@ -1013,6 +1020,7 @@ contextCmd
   .description('Fetch a comparison context bundle')
   .argument('<comparison-id>', 'Comparison ID to fetch context for')
   .option('--source <source>', 'Context source: auto, cloud, or local', 'auto')
+  .option('--agent', 'Normalize JSON evidence for LLM agents')
   .option(
     '--similar-limit <n>',
     'Maximum similar fingerprint matches to return (1-50)',
@@ -1036,6 +1044,7 @@ Examples:
   $ vizzly context comparison def456 --source local
   $ vizzly context comparison def456 --source cloud --similar-limit 5 --recent-limit 5
   $ vizzly context comparison def456 --source cloud --json
+  $ vizzly context comparison def456 --source cloud --agent --json
 `
   )
   .action(async (comparisonId, options) => {