diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3c7f2e9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+
+ 
+
+
+# Schwert und Magie on Pebble
+
+A port of the classic German C64 text-adventure RPG series **Schwert und Magie**
+(German Design Group, 1989–1992) to the Pebble Time 2 smartwatch.
+
+## Architecture
+
+The phone runs VICE 3.8 as a companion app and streams the C64 text screen to
+the watch. Button presses on the watch flow back to VICE via Bluetooth.
+
+
+
+## The game
+
+*Schwert und Magie* is an 8-episode text-adventure / RPG series for the
+Commodore 64, published in German by boeder-Verlag. Two episodes share one
+disk:
+
+| Disk | Episodes |
+|------|----------|
+| I | Folge 1: Das geheimnisvolle Kraut · Folge 2: Der unheimliche Tempel |
+| II | Folge 3: Das Piratenhaus · Folge 4: Die Burg des Magiers |
+| III | Folge 5: Das Haus des Vampirs · Folge 6: Der Turm des Todes |
+| IV | Folge 7: Unter Wasser · Folge 8: Insel der Wunder |
+
+The copy-protection scheme asks for a word from the printed *Anleitung*
+(manual). The app includes the full manual text with a look-up button (📖) so
+you can answer the prompt without keeping the paper around.
+
+## Repository layout
+
+```
+SchwertUndMagieOnPebbleWatchApp/ Pebble watchapp (C + PebbleKit JS)
+SchwertUndMagieOnPebbleCompanionApp/ Android companion app (Kotlin + NDK)
+versions/ Original .d64 disk images (4 disks)
+docs/ Architecture notes and diagrams
+dist/ Built APKs (gitignored)
+```
+
+## How it works
+
+Three processes cooperate across two devices:
+
+```
+Pebble watch
+ │ Bluetooth AppMessage
+ ▼
+Core for Pebble (on phone) — PebbleKit JS bridge
+ │ HTTP on 127.0.0.1:8888
+ ▼
+Android companion app — NanoHTTPD server
+ │ JNI
+ ▼
+VICE 3.8 (C64 emulator, cross-compiled for ARM64/x86_64)
+```
+
+The watch displays the C64 text screen (40×25 cells) in a scroll view and
+provides a key wheel for the number keys most used by the game. The companion
+app renders VICE's 320×200 framebuffer on-screen and also provides a virtual
+C64 keyboard for direct input.
+
+See [`docs/architecture.md`](docs/architecture.md) for the full design.
+
+## Requirements
+
+- **Android phone** running Android 7.0+ (API 24)
+- **Pebble Time 2** (or any Pebble running firmware 3.x — the `.pbw` targets
+ all SDK 3 platforms)
+- **Core for Pebble** installed on the phone (the community Pebble app)
+- **C64 ROM files** — `kernal`, `basic`, `chargen`, `1541` — legally obtained
+ from your own C64 or from Cloanto's C64 Forever. The app prompts you to
+ import them on first launch; they are never bundled.
+- **Disk images** — `.d64` or `.g64` files for the four game disks. You can
+ import your own or use the in-app **Fetch Disks** button to download
+ community-preserved dumps from the Internet Archive's C64 Preservation
+ Project (requires nibtools, which is cross-compiled automatically).
+
+## Building
+
+### Android companion app
+
+```bash
+cd SchwertUndMagieOnPebbleCompanionApp
+./gradlew assembleDebug # debug build
+./gradlew assembleRelease # signed release build (requires keystore.properties)
+./gradlew installDebug # build + install on connected device
+```
+
+VICE 3.8 and nibtools are cross-compiled automatically the first time — the
+Gradle `buildVice` and `buildNibtools` tasks unpack the source tarballs from
+`res/` and build `libvice.a` / `libnibtools.a` for ARM64 and x86_64. The NDK
+must be installed (Android Studio → SDK Manager → SDK Tools → NDK (Side by
+side)).
+
+### Pebble watch app
+
+```bash
+cd SchwertUndMagieOnPebbleWatchApp
+pebble build
+pebble install --phone
+```
+
+In headless / CI environments add `--vnc` to every emulator command.
+
+## Getting disk images onto the device
+
+**Option A — Fetch Disks button** (in-app)
+Opens a dialog, downloads all 8 episode disks as `.nbz` files from the
+Internet Archive C64 Preservation Project, and converts them to G64 using
+nibtools. Requires a network connection; conversion runs on-device.
+
+**Option B — manual copy**
+Copy `.d64` or `.g64` files to the app's external files directory via USB or
+`adb push`, matching the names expected by the drawer (e.g. `SCHWUM1A.D64`).
+
+## Hero saves
+
+Hero characters are stored on separate hero disks (up to 3 slots). The app
+manages these from the drawer — create a new hero disk, load an episode disk,
+then swap to the hero disk when the game asks for it. A built-in stat editor
+lets you inspect and edit a saved hero's attributes directly.
+
+## Save states
+
+The 💾 button saves or restores a full VICE snapshot (CPU registers, RAM,
+VICII, SID, CIA) to one of three slots. Snapshots go through a CPU trap to
+ensure register consistency — see `docs/architecture.md §4.4`.
+
+## Publishing
+
+See [`docs/publish.md`](docs/publish.md) for keystore setup, Google Play,
+F-Droid, and Rebble submission.
+
+## License
+
+The watch app and companion app source code in this repository are released
+under the **MIT License**.
+
+The *Schwert und Magie* game content (disk images, manual text) remains the
+property of its original authors and is not part of this license. VICE and
+nibtools are GPLv2 and are built from source at compile time; their source
+tarballs in `res/` are not covered by this repository's MIT license.