first

README.md

@@ -1,3 +1,29 @@
 # Hermes
 
-Hermes is the internal name of this project
+Hermes is a native iOS and Android prototype for a sports-betting research study.
+The app is designed to feel premium, fast, and clear while keeping the server
+authoritative for timing, odds, settlement, and analytics.
+
+## Goals
+
+- Native UI on iOS and Android
+- English and Swedish from day one
+- Research-first flow, not real-money betting
+- Structured analytics and audit logging
+- Stable backend and API contracts for iteration
+
+## Repo Layout
+
+- `backend/` Rust API and migrations
+- `contracts/` OpenAPI and localization contracts
+- `docs/` architecture, schema, and state-machine docs
+- `infra/` local environment and deployment assets
+- `mobile/` native app scaffolds
+- `fixtures/` sample media and test data
+- `scripts/` helper automation
+
+## Status
+
+The repository has been initialized with the first planning and backend
+foundation artifacts. The remaining work is to fill out the domain modules and
+native clients.