feat: checkpoint device agent runtime milestones

README.md

@@ -0,0 +1,29 @@
+# Device Agent Runtime
+
+Device Agent Runtime is a device-agnostic runtime for LLM-driven automation.
+It gives agents a stable way to observe, decide, and act against real devices
+through a small set of domain models, driver contracts, tools, perception
+providers, and runtime orchestration.
+
+iPhone automation through WebDriverAgent/Appium is the first driver, not the
+platform boundary. Future drivers can target Android, browsers, desktop
+environments, or other device surfaces without changing the runtime's core
+contracts.
+
+## Current Shape
+
+- `core/`: shared domain models and runtime errors.
+- `driver/`: the `Driver` contract, concrete driver adapters, and driver-type
+  registry.
+- `device/`: device lifecycle and active driver management.
+- `tools/`: device capabilities exposed to runtime and API layers.
+- `perception/`: screen-to-`Scene` perception behind `PerceptionProvider`.
+- `runtime/`: planning and execution orchestration.
+- `api/`: REST/MCP transport adapters.
+- `storage/`: timeline, task, and device configuration persistence.
+
+## Project Direction
+
+The durable roadmap is in [docs/ROADMAP.md](docs/ROADMAP.md). The architecture
+invariants future changes must preserve are in
+[docs/CONSTITUTION.md](docs/CONSTITUTION.md).