image-compress-and-docs

name	image-compress-and-docs
description	Capture, optimize, and publish screenshots to Astro docs. Use when asked to take screenshots for docs, update doc images, compress PNG assets, or add visual documentation to the agentv.dev docs site. Triggers on "add screenshots to docs", "update docs images", "compress screenshots", "optimize PNG", "document with screenshots".

Image Compression & Docs Update

Capture browser screenshots, optimize them for the web, and publish to the Astro docs site at apps/web/src/content/docs/.

Prerequisites

Install optimization tools if not present:

# Ubuntu/Debian (usually pre-installed)
sudo apt-get install -y pngquant optipng

# macOS
brew install pngquant optipng

Verify:

which pngquant optipng

Step 1 — Capture Screenshots

Use agent-browser with a named session and 1440×860 viewport for docs-quality screenshots. Always use --session to isolate, never --headed.

# Start the target server first (e.g., Dashboard)
bun apps/cli/src/cli.ts dashboard --port 14800 &
sleep 3

# Open, set viewport, navigate, screenshot
agent-browser --session docs-shots open http://localhost:14800
agent-browser --session docs-shots wait --load networkidle
agent-browser --session docs-shots set viewport 1440 860
agent-browser --session docs-shots snapshot -i          # discover refs
agent-browser --session docs-shots click <ref>          # navigate if needed
agent-browser --session docs-shots wait --load networkidle
agent-browser --session docs-shots screenshot           # saved to /run/user/1000/agent-browser/tmp/screenshots/

# Clean up
agent-browser --session docs-shots close
kill $(lsof -ti:14800) 2>/dev/null

Screenshots with realistic data: Dashboard screenshots must have populated data — multiple runs with varying pass rates and real targets. If results are sparse, create synthetic run bundles under .agentv/results/<run_id>/ with summary.json plus .internal/index.jsonl rows before launching Dashboard.

Synthetic JSONL record format:

{"test_id": "my-test", "score": 0.95, "target": "claude-sonnet", "experiment": "default", "timestamp": "2026-04-08T09:15:44.003Z", "status": "pass", "suite": "my-suite", "duration_ms": 3500, "token_usage": {"input_tokens": 1200, "output_tokens": 400}, "scores": [{"type": "llm-rubric", "score": 0.95, "pass": true}], "grading_path": "my-test--demo/sample-1/grading.json", "metrics_path": "my-test--demo/sample-1/metrics.json", "error": null}

Step 2 — Optimize

Always apply both passes: pngquant (lossy, 50–70% savings) then optipng (lossless polish).

SHOT="/run/user/1000/agent-browser/tmp/screenshots/screenshot-<id>.png"
OUT="/home/christso/projects/agentv/apps/web/src/assets/screenshots/my-feature.png"

# Pass 1: lossy quantization (creates <name>-fs8.png or use --output)
pngquant --quality 80-95 --force --output /tmp/opt.png "$SHOT"

# Pass 2: lossless polish
optipng -o5 -quiet /tmp/opt.png

# Copy to docs assets
cp /tmp/opt.png "$OUT"

# Check savings
ls -lh "$SHOT" "$OUT"

Typical results: 116 KB raw → 44 KB optimized (62% reduction).

For multiple files:

SHOTS_DIR="/run/user/1000/agent-browser/tmp/screenshots"
ASSETS_DIR="/home/christso/projects/agentv/apps/web/src/assets/screenshots"

for f in shot1.png shot2.png shot3.png; do
  pngquant --quality 80-95 --force --output "$SHOTS_DIR/opt-$f" "$SHOTS_DIR/$f"
  optipng -o5 -quiet "$SHOTS_DIR/opt-$f"
  cp "$SHOTS_DIR/opt-$f" "$ASSETS_DIR/$f"
done
ls -lh "$ASSETS_DIR"

Step 3 — Update Astro Docs

Docs live at: apps/web/src/content/docs/docs/next/
Assets live at: apps/web/src/assets/screenshots/

Import pattern (Astro <Image> for automatic optimization):

import { Image } from 'astro:assets';
import myFeature from '../../../../assets/screenshots/my-feature.png';
import myDetail from '../../../../assets/screenshots/my-detail.png';

<Image src={myFeature} alt="Descriptive alt text for accessibility" />

Alt text rules:

• Describe what the screenshot shows, not just what the feature is
• Include key data visible in the image (e.g., "showing 100% pass rate across 5 tests")
• Never use "screenshot of" — just describe the content

Placement:

• Put the hero image directly after the intro paragraph (before ## Usage)
• Put feature-specific images directly after the section that describes them
• Don't cluster all images at the top or bottom

Step 4 — Commit

# Feature branch: UI changes
cd /path/to/worktree
git add apps/dashboard/...
git commit -m "fix(studio): ..."

# Main repo: docs changes  
cd /home/christso/projects/agentv
git add apps/web/src/assets/screenshots/ apps/web/src/content/docs/
git commit -m "docs(<feature>): add screenshots and update documentation"
git push

Checklist

• Screenshots show realistic data (multiple runs, real targets, varying scores)
• Viewport set to 1440×860 before capturing
• Both pngquant and optipng applied
• File size verified (target: <50 KB per screenshot)
• Alt text is descriptive and specific
• Image placed close to the content it illustrates
• Astro <Image> component used (not raw <img>)
• Docs committed separately from code changes