From c40cb6e75a29bdd8241b7d182ec99108f685d094 Mon Sep 17 00:00:00 2001
From: Davide Scaini <davide.scaini@alumni.cern>
Date: Thu, 4 Jun 2026 00:24:08 +0200
Subject: [PATCH] docs: mention AGPL v3 license in README

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b0f62ec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# Bincio Mobile App
+
+An Expo/React Native mobile app for managing cycling activities locally on your phone.
+
+**Features:**
+- 📱 Local-first: all activity data lives on your device
+- 🗺️ FIT/GPX/TCX import with local extraction (via Pyodide)
+- 📊 Activity detail: maps, elevation profiles, metric charts
+- ☁️ Optional sync to a remote Bincio instance
+- 🤖 Karoo 2 integration: auto-import from device storage
+- 📴 Works offline — no account required
+
+---
+
+## Getting Started
+
+```bash
+npm install
+npx expo start
+```
+
+Install **Expo Go** from the Play Store / App Store and scan the QR code to run the app on your phone.
+
+For native module support (maps, file extraction), use a **Development Build** instead of Expo Go. See [DEVELOPMENT.md](./DEVELOPMENT.md) for full setup instructions.
+
+---
+
+## Documentation
+
+- **[DEVELOPMENT.md](./DEVELOPMENT.md)** — How to build, run, and deploy the app
+  - Prerequisite tools & setup
+  - Two build modes (Expo Go vs Development Build)
+  - Android & iOS development
+  - APK building & distribution
+  - Karoo 2 sideloading
+  - Troubleshooting
+
+- **Full design document** — For detailed architectural info, sync protocol, data model, and known issues:
+  - Location: `/Users/brutsalvadi/src/bincio_activity/docs/mobile-app.md`
+  - Topics: Pyodide integration, Karoo constraints, implementation phases, technical debt
+
+---
+
+## Project Structure
+
+```
+├── app/                      — Expo Router screens
+│   ├── (tabs)/              — Tab screens (Feed, Import, Settings)
+│   └── activity/[id].tsx    — Activity detail screen
+├── components/              — Reusable UI components
+├── db/                       — SQLite schema, queries, sync logic
+├── extraction/              — Pyodide WebView & extraction engine
+├── ThemeContext.tsx         — Theme & color palette
+├── app.json                 — Expo config
+├── metro.config.js          — React Native bundler config
+└── tsconfig.json            — TypeScript config
+```
+
+---
+
+## Technology
+
+- **Framework:** Expo (React Native) + TypeScript
+- **Database:** SQLite (expo-sqlite)
+- **Maps:** MapLibre (with SVG fallback for Android < 29)
+- **File extraction:** Pyodide (Python in WebView)
+- **Build:** EAS Build + local Prebuild
+
+---
+
+## Quick Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npm install` | Install dependencies |
+| `npx expo start` | Start Expo dev server (use with Expo Go app) |
+| `npx expo run:android` | Build & run Development Build on Android device/emulator |
+| `npx expo run:ios` | Build & run on iOS device |
+| `npx expo prebuild --clean` | Generate native Android/iOS projects |
+| `eas build -p android --profile preview` | Build standalone APK in the cloud |
+
+---
+
+## Where the code came from
+
+This repository was split from `bincio_activity`, which contains:
+- Backend Python library (`bincio/`) — extraction, database, API server
+- Web frontend (`site/`) — Astro app
+- Original mobile code (now here)
+
+The mobile app is designed to work standalone but can sync with a Bincio instance for backup and web access.
+
+---
+
+## License
+
+[AGPL v3](LICENSE) — see the `LICENSE` file for details.