# AGENTS.md

This project is a focused deterministic website action topology engine.

## Scope

Build and maintain only the topology engine:

- Capture page states.
- Extract actionable elements.
- Generate and verify locator candidates.
- Record action edges and observable effects.
- Emit graph artifacts that other projects can consume.

Do not turn this repository into a general browser agent platform. LLM planning, natural-language task execution, orchestration, and product UI belong in separate projects.

## Commands

- `npm install` — install dependencies.
- `npm run typecheck` — TypeScript type check.
- `npm run build` — compile to `dist/`.
- `npm run scan -- --url ./examples/simple.html --out artifacts/simple-scan.json` — static scan.
- `npm run example` — low-risk exploration of the local example page.

## Implementation Notes

- Prefer Playwright user-facing locator strategies first: role, label, placeholder, text, test id.
- Keep CSS locators as fallback candidates, not the primary source of truth.
- Bind elements to states. Do not treat a DOM node as globally meaningful outside its page state.
- Preserve risk gating. High-risk terms such as delete, submit, pay, confirm, and authorize must not be clicked by the default explorer.
- Keep source discussions under `docs/source/` when they drive design decisions.