feat: add topology graph v0.2.2 contract

README.md

@@ -11,11 +11,13 @@ The project intentionally does not include an LLM, a generic browser agent, or a
 - 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, context scopes, identity checks, and verification evidence.
+- Compile scoped locator descriptors for row/dialog/form/list-item contexts when they can make duplicated targets executable.
 - Optionally run low-risk one-hop click exploration from a clean entry state.
 - Replay actions from the entry state and record observed state transitions with snapshot-diff effects.
+- Record navigation failures as failed observations when a graph can still be emitted.
 - Record state-local skipped default-exploration actions when risk policy blocks them.
 - Record failed observations instead of turning failed locators or failed actions into successful edges.
-- Emit state nodes, elements, locators, action edges, skipped actions, failed observations, and metadata in JSON.
+- Emit state nodes, elements, locators, action edges, skipped actions, failed observations, metadata, and summary counts in JSON.
 
 ## Non-Goals
 
@@ -52,6 +54,12 @@ Entry-state low-risk exploration:
 npm run example
 ```
 
+Timeout tuning for slow sites:
+
+```bash
+npm run explore -- --url https://www.gov.cn/ --out artifacts/govcn.json --max-actions 2 --navigation-timeout-ms 60000 --action-timeout-ms 3000
+```
+
 Build:
 
 ```bash
@@ -60,7 +68,7 @@ npm run build
 
 ## Output Model
 
-The output JSON follows the schema described in [schemas/topology-graph.schema.md](schemas/topology-graph.schema.md).
+The output JSON follows the schema described in [schemas/topology-graph.schema.md](schemas/topology-graph.schema.md). A machine-checkable JSON Schema is available at [schemas/topology-graph.schema.json](schemas/topology-graph.schema.json).
 
 Key objects:
 
@@ -72,6 +80,7 @@ Key objects:
 - `EffectRecord`: snapshot-diff record for `url`, `dom`, `visibleText`, or `actionableInventory`, with `before` and `after` values.
 - `SkippedAction`: risk-policy default exploration refusal with risk category, reason, state id, element id, and evidence.
 - `FailedObservation`: locator, actionability, action, or effect failure with machine-readable reason and diagnostic evidence.
+- `summary`: count totals and grouped counts for edges, skipped actions, and failed observations.
 
 ## Source Notes