gsd-browser

<essential_principles>

The daemon auto-starts. Never run gsd-browser daemon start. It launches on first command. Only use daemon stop to clean up when finished.

Always re-snapshot after page changes. Refs are versioned (@v1:e1, @v2:e3). After navigation, form submission, or dynamic content loading, old refs are stale. Run gsd-browser snapshot to get fresh refs before interacting.

Use --json when parsing output. Use text mode when reading output yourself. Use --json when you need to extract values programmatically.

Positional args have no flag prefix. Commands like click, type, hover take positional args. Do NOT add --selector:

• gsd-browser click "button.submit" (correct)
• gsd-browser click --selector "button.submit" (WRONG)

Core workflow pattern: Every browser automation follows: navigate -> snapshot -> interact -> re-snapshot (after DOM changes).

gsd-browser navigate https://example.com
gsd-browser snapshot
# Read snapshot output: @v1:e1 [input type="email"], @v1:e2 [button] "Submit"
gsd-browser fill-ref @v1:e1 "user@example.com"
gsd-browser click-ref @v1:e2
gsd-browser wait-for --condition network_idle
gsd-browser snapshot  # REQUIRED - old refs are now stale

Command chaining: Use && when you don't need intermediate output. Run separately when you need to parse output first (e.g., snapshot to discover refs, then interact).

Global options available on all commands:

Flag	Purpose
--json	Structured JSON output
--browser-path <path>	Path to Chrome/Chromium
--session <name>	Named session for parallel instances

</essential_principles> <routing>

Based on what the user needs, read the appropriate workflow:

User intent	Workflow
Navigate, click, type, fill forms, interact with pages	workflows/navigate-and-interact.md
Scrape data, extract content, read page structure	workflows/scrape-and-extract.md
Test pages, run assertions, visual regression, mock network	workflows/test-and-assert.md
Debug issues, check logs, diagnose problems	workflows/debug-and-diagnose.md
Install, configure, set up sessions	workflows/setup-and-configure.md

After reading the workflow, follow it. Load references only when the workflow directs you to.

</routing> <reference_index>

All domain knowledge in references/:

Commands: command-reference.md (all 63 commands with exact syntax) Snapshots: snapshot-and-refs.md (versioned refs, snapshot modes) Intents: semantic-intents.md (15 predefined intents for find-best/act) Errors: error-recovery.md (common errors and fixes) Config: configuration.md (TOML config, env vars, 5-layer merge)

</reference_index> <workflows_index>

Workflow	Purpose
navigate-and-interact.md	Page navigation, clicking, typing, forms, intents
scrape-and-extract.md	Data extraction, accessibility tree, page source
test-and-assert.md	Assertions, visual regression, network mocking, test generation
debug-and-diagnose.md	Console/network logs, timeline, debug bundles
setup-and-configure.md	Installation, configuration, sessions, daemon management

</workflows_index> <success_criteria>

Browser automation task is complete when:

• Target page state is achieved and verified (via assertions or visual confirmation)
• Daemon is stopped if no further browser work is needed (gsd-browser daemon stop)
• Extracted data is returned in the expected format
• Any saved state (auth, cookies) is persisted for reuse if appropriate

</success_criteria>