doc-visual

Visual Documentation Generator

Systematically capture screenshots, videos, and GIFs of Momentum CMS flows using agent-browser CLI. Outputs organized into docs/​visuals/ by feature.

Quick Start

/​doc-visual dashboard              # Capture dashboard screenshots
/​doc-visual auth                   # Capture login, setup, forgot-password
/​doc-visual collections            # Capture CRUD flows
/​doc-visual all                    # Capture everything
/​doc-visual all --responsive       # Everything + responsive breakpoints
/​doc-visual all --video            # Everything + WebM recordings of flows
/​doc-visual navigation --headed    # Watch the capture in a visible browser

Workflow Overview

Every capture session follows 5 phases. Do not skip phases.

---

Phase 0: Prerequisites

Before capturing anything, verify the environment is ready.

1. Dev Server

# Check if the dev server is running
agent-browser open "http://localhost:4200"
agent-browser wait --load networkidle
agent-browser get title

If the server is not running, start it:

nx serve example-angular &
# Wait for compilation
sleep 15
agent-browser open "http://localhost:4200"
agent-browser wait --load networkidle

IMPORTANT: The correct command is nx serve example-angular, NOT nx serve cms-admin.

2. Output Directory

mkdir -p docs/​visuals/​{auth,dashboard,collections,fields,media,navigation,plugins,theme,responsive,kitchen-sink}

3. Auth State

Check if a saved auth state exists:

if [ -f docs/​visuals/​.auth-state.json ]; then
    agent-browser state load docs/​visuals/​.auth-state.json
    agent-browser open "http://localhost:4200/admin"
    agent-browser wait --load networkidle
    # Verify we're on the dashboard, not redirected to login
    URL=$(agent-browser get url)
    if echo "$URL" | grep -q "login\|setup"; then
        echo "Auth state expired, re-authenticating..."
        # Proceed to Phase 2
    fi
fi

If no auth state or expired, proceed to Phase 2.

---

Phase 1: Argument Parsing

Parse the flow argument to determine what to capture:

Flags

---

Phase 2: Authentication

If no valid auth state exists, authenticate:

First-Time Setup (if /​admin redirects to /​admin/​setup)

agent-browser open "http://localhost:4200/admin"
agent-browser wait --load networkidle

# Check if we're on setup page
URL=$(agent-browser get url)
if echo "$URL" | grep -q "setup"; then
    # Capture setup page BEFORE filling
    agent-browser screenshot docs/​visuals/​auth/​setup-light.png

    agent-browser snapshot -i
    # Fill setup form: name, email, password
    agent-browser fill @e1 "Admin User"
    agent-browser fill @e2 "[email protected]"
    agent-browser fill @e3 "TestPassword123!"
    agent-browser click @e4  # Submit button
    agent-browser wait --load networkidle
fi

Login (if redirected to /​admin/​login)

URL=$(agent-browser get url)
if echo "$URL" | grep -q "login"; then
    # Capture login page BEFORE filling
    agent-browser screenshot docs/​visuals/​auth/​login-light.png

    agent-browser snapshot -i
    agent-browser fill @e1 "[email protected]"
    agent-browser fill @e2 "TestPassword123!"
    agent-browser click @e3  # Login button
    agent-browser wait --load networkidle
fi

Save Auth State

agent-browser state save docs/​visuals/​.auth-state.json

The .auth-state.json file is gitignored and contains session tokens.

---

Phase 3: Capture Execution

For each requested flow, follow the capture pattern:

Standard Capture Pattern

# 1. Navigate
agent-browser open "<url>"
agent-browser wait --load networkidle

# 2. Set viewport (desktop default)
agent-browser set viewport 1280 800

# 3. Wait for rendering
agent-browser wait 500

# 4. Capture light mode
agent-browser screenshot docs/​visuals/<category>/<name>-light.png

# 5. Toggle dark mode
agent-browser snapshot -i
# Find and click theme toggle, or use JS:
agent-browser eval "document.documentElement.classList.add('dark')"
agent-browser wait 500

# 6. Capture dark mode
agent-browser screenshot docs/​visuals/<category>/<name>-dark.png

# 7. Reset to light mode
agent-browser eval "document.documentElement.classList.remove('dark')"

Responsive Capture Pattern

# Mobile (iPhone)
agent-browser set viewport 375 812
agent-browser wait 500
agent-browser screenshot docs/​visuals/<category>/<name>-mobile.png

# Tablet (iPad)
agent-browser set viewport 768 1024
agent-browser wait 500
agent-browser screenshot docs/​visuals/<category>/<name>-tablet.png

# Desktop
agent-browser set viewport 1280 800
agent-browser wait 500
agent-browser screenshot docs/​visuals/<category>/<name>-desktop.png

# Large Desktop
agent-browser set viewport 1920 1080
agent-browser wait 500
agent-browser screenshot docs/​visuals/<category>/<name>-desktop-lg.png

Video Recording Pattern

agent-browser record start docs/​visuals/<category>/<name>-flow.webm

# Perform steps with pauses for visibility
agent-browser open "<url>"
agent-browser wait --load networkidle
agent-browser wait 1000  # Pause for viewer

agent-browser snapshot -i
agent-browser click @e1
agent-browser wait 1000  # Pause for viewer

# ... more steps ...

agent-browser record stop

Flow-Specific Instructions

See references/​flow-catalog.md for the complete catalog of every flow with exact URLs, steps, and expected screenshot filenames.

---

Phase 4: Post-Processing

Generate Visual Index

After all captures are complete, generate docs/​visuals/​README.md:

./​templates/​generate-visual-index.sh

Or manually create it — the index should:

1. List all captured images organized by category
2. Use inline markdown image syntax: ![Alt text](category/filename.png)
3. Show light/​dark comparisons side-by-side using HTML tables
4. Link to WebM videos (note: WebM doesn't render inline on GitHub)

Optional: Convert WebM to GIF

If ffmpeg is available:

ffmpeg -i docs/​visuals/​auth/​login-flow.webm \
  -vf "fps=10,scale=800:-1:flags=lanczos" \
  -loop 0 \
  docs/​visuals/​auth/​login-flow.gif

Install ffmpeg if needed: brew install ffmpeg

Optional: Update Existing Docs

Embed screenshots in the relevant documentation files:

Use relative paths from the doc file:

![Admin Dashboard](../visuals/dashboard/dashboard-light.png)

---

Phase 5: Verification

After all captures, verify the output:

Use the Glob tool (not find via Bash) to count and verify files:

1. Count screenshots: Glob("docs/​visuals/​**/​*.png")
2. Count videos: Glob("docs/​visuals/​**/​*.webm")
3. Count GIFs: Glob("docs/​visuals/​**/​*.gif")
4. Check for zero-size files: ls -la docs/​visuals/​**/​*.png and inspect sizes

Report a summary:

• Total screenshots captured
• Total videos recorded
• Any failed captures (zero-size files)
• Categories covered
• Any flows that couldn't be captured (e.g., plugin pages not enabled)

---

Naming Conventions

All filenames use kebab-case, no spaces, no timestamps (idempotent overwrites).

---

Browser Automation Options

Option 1: agent-browser CLI (Default)

Best for headless, scriptable captures. Works without a GUI.

agent-browser open "http://localhost:4200/admin"
agent-browser screenshot docs/​visuals/​dashboard/​dashboard-light.png

Option 2: Claude-in-Chrome MCP

Best for interactive debugging and GIF creation (MCP has a built-in gif_creator tool).

mcp__claude-in-chrome__tabs_context_mcp({ createIfEmpty: true })
mcp__claude-in-chrome__navigate({ url: "http://localhost:4200/admin", tabId })
mcp__claude-in-chrome__computer({ action: "screenshot", tabId })

Prefer agent-browser for batch captures. Use Claude-in-Chrome when you need interactive exploration or the GIF creator.

---

Deep-Dive Documentation

Ready-to-Use Templates

# Examples
./​templates/​capture-flow.sh http://localhost:4200/admin docs/​visuals/​dashboard dashboard
./​templates/​capture-responsive.sh http://localhost:4200/admin docs/​visuals/​responsive admin
./​templates/​capture-crud-flow.sh articles docs/​visuals/​collections
./​templates/​record-video-flow.sh http://localhost:4200/admin/login docs/​visuals/​auth login
./​templates/​generate-visual-index.sh