Make UI change → Run CUJs → Review screenshots → 
  ├─ Looks good? → Update GIFs, commit, share link
  └─ Looks wrong? → Fix bug, repeat

uv run --with playwright playwright install chromium

import asyncio
from playwright.async_api import async_playwright
import os

async def capture_my_cuj():
    output_dir = "/tmp/cuj-screenshots/my-cuj"
    os.makedirs(output_dir, exist_ok=True)
    
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        context = await browser.new_context(
            viewport={"width": 390, "height": 844},  # Mobile
            device_scale_factor=2  # Retina
        )
        page = await context.new_page()
        
        # Step 1
        await page.goto("http://localhost:5173")
        await page.wait_for_timeout(1500)
        await page.screenshot(path=f"{output_dir}/01-initial.png")
        
        # Step 2: Interact
        await page.click("button:has-text('Submit')")
        await page.wait_for_timeout(1000)
        await page.screenshot(path=f"{output_dir}/02-submitted.png")
        
        # ... more steps
        
        await browser.close()

if __name__ == "__main__":
    asyncio.run(capture_my_cuj())

uv run --with playwright python my_cuj.py

convert -delay 150 -loop 0 /tmp/cuj-screenshots/my-cuj/*.png output.gif

mv output.gif docs/gifs/my-cuj.gif
git add docs/gifs/my-cuj.gif docs/CUJs.md
git commit -m "docs: add my-cuj GIF"
git push

# Click button by text
await page.click("button:has-text('Submit')")

# Fill input
await page.fill("input[name='email']", "test@example.com")

# Select dropdown
await page.select_option("select#plan", "premium")

# Wait for element
await page.wait_for_selector(".success-message")

# Scroll
await page.evaluate("window.scrollBy(0, 300)")

# Keyboard shortcut
await page.keyboard.press("Escape")

# Critical User Journeys (CUJs)

## CUJ 1: App Tour

**Goal:** Navigate the main app layout.

**Steps:**
1. Open app → Activity tab
2. Switch to Live tab
3. Return to Activity

![App Tour](./gifs/cuj1-app-tour.gif)

---

## CUJ 2: Create Task

**Goal:** Create a new plan and task.

**Steps:**
1. Click "+ Plan"
2. Enter name, submit
3. Click "+ Task"
4. Enter name, submit

![Create Task](./gifs/cuj2-create-task.gif)

# 1. Make UI changes
# 2. Start servers
# 3. Capture CUJs
uv run --with playwright python scripts/capture-cujs.py

# 4. Review screenshots (agent can view these)
# 5. Create GIFs
convert -delay 150 -loop 0 /tmp/cuj-screenshots/cuj1/*.png docs/gifs/cuj1.gif

# 6. Update CUJs.md with new steps/descriptions
# 7. Commit everything
git add docs/CUJs.md docs/gifs/
git commit -m "docs: update CUJ screenshots after UI changes"
git push