Initialize action topology engine

README.md

@@ -0,0 +1,63 @@
+# Action Topology Engine
+
+Small deterministic tool for building a website action topology graph.
+
+The project intentionally does not include an LLM, a generic browser agent, or a large workflow platform. Its job is to observe a site, describe states and actionable elements, generate verifiable locator candidates, and record action edges with observable effects.
+
+## Current Scope
+
+- Open a URL or local HTML file with Playwright.
+- Capture one page state with DOM and visible-text fingerprints.
+- Extract actionable elements: buttons, links, inputs, selects, textareas, roles, tab stops, and click handlers.
+- Generate locator candidates with scores.
+- Optionally explore low-risk click actions from the entry state.
+- Record state nodes, elements, locators, action edges, and basic effects in JSON.
+
+## Non-Goals
+
+- No LLM decision making.
+- No natural-language task planner.
+- No high-risk automatic actions.
+- No attempt to fully recover frontend business functions in the first version.
+
+## Install
+
+```bash
+npm install
+```
+
+## Commands
+
+Static scan:
+
+```bash
+npm run scan -- --url ./examples/simple.html --out artifacts/simple-scan.json
+```
+
+Entry-state low-risk exploration:
+
+```bash
+npm run example
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+## Output Model
+
+The output JSON follows the schema described in [schemas/topology-graph.schema.md](schemas/topology-graph.schema.md).
+
+Key objects:
+
+- `StateNode`: URL, route, title, state hashes, modal stack, and entry metadata.
+- `ActionableElement`: element semantics, visibility, bounding box, and locator candidates.
+- `LocatorCandidate`: Playwright-friendly locator descriptors plus score and verification status.
+- `ActionEdge`: action from one state to another through an element, with effects and risk.
+
+## Source Notes
+
+The originating ChatGPT share conversation is preserved in [docs/source/chatgpt-share-6a30e583.md](docs/source/chatgpt-share-6a30e583.md).
+