Initialize action topology engine

AGENTS.md

@@ -0,0 +1,32 @@
+# 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.
+