# AGENTS.md

Use this repo's agent-facing assets before inventing new screenshot capture, batching, or storage patterns.

## Discoverability

- Start with [CAPABILITIES.md](CAPABILITIES.md) for a task-to-entrypoint map.
- If `infra-screenshot` is already installed, inspect `screenshot.capabilities`.
- For copyable patterns, check [examples/](examples).
  Notable additions:
  `cli_jsonl_batch_capture.py` for nested JSONL CLI batches.
  `playwright_scrolling_depth_capture.py` for scroll-enabled, depth-limited capture.
  `custom_viewport_and_html_snapshot.py` for validated custom viewport + HTML snapshot capture.
  `playwright_motion_snapshot.py` for Playwright-only GIF motion artifacts.
- When behavior is subtle, use [tests/](tests) as an executable reference.
- Local task-specific instructions live in [skills/](skills).
- Prefer public imports from `screenshot` or documented public modules like `screenshot.backends` over private implementation details.

## Local Skills

- `infra-screenshot-local-cli`
  Use for local CLI capture, JSONL batch input, summary files, and backend selection.
- `infra-screenshot-playwright-capture`
  Use for programmatic Playwright capture, viewport configuration, timeout behavior, and browser policy.
- `infra-screenshot-selenium-capture`
  Use for Selenium-backed capture, Chrome/driver configuration, and backend parity questions.
- `infra-screenshot-service-storage`
  Use for `ScreenshotService`, multi-job orchestration, storage backends, and batch summary handling.

## Repo Conventions

- When you add or change public helpers, update both [CAPABILITIES.md](CAPABILITIES.md) and [src/screenshot/capabilities.py](src/screenshot/capabilities.py).
- Keep docs and examples task-oriented: lead with "use this for X", not implementation trivia.
- Prefer public `screenshot` imports for runners, models, storage backends, and outcomes.
- Prefer `ScreenshotService` or `build_local_screenshot_service()` from `screenshot.backends` over ad-hoc batching loops.
- Prefer `result.outcome` for operational status and `result.has_artifacts` when partial artifacts matter.
- Use tests as usage references when behavior is subtle; the most useful files are in [tests](tests).
- Run `make verify` for the local full gate, `make verify-ci` for the PR-equivalent gate, and `make verify-build` for release-build verification.
- Do not claim the branch is ready, verification is clean, or CI-equivalent unless `bash scripts/verify.sh --skip-build` has passed on the final tree after the last edit.
- For release/tag/publish readiness, also require `bash scripts/verify.sh --skip-tests` on the final tree.
- Any edit after verification invalidates readiness; rerun the relevant verify script before reporting status.
- Do not treat `uv run ruff check ...` or targeted test runs as a substitute for the repo verify scripts. CI also runs formatters, mypy, the reliability subset, and build checks.

## infra-core

This repo depends on `infra-core`. Prefer its shared helpers before writing custom filesystem glue, retry logic, or other shared automation primitives.

- Check `infra_core.capabilities` for a task-oriented capability index.
- If this repo vendors or submodules `infra-core`, also read its `CAPABILITIES.md`.
- Prefer public `infra_core` imports over internal module paths.

## Downstream Repos

If another repo depends on `infra-screenshot`, copy the guidance from [agent-snippets/downstream-AGENTS.md](agent-snippets/downstream-AGENTS.md) into that repo's own `AGENTS.md`.
