diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..7438162
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,90 @@
+# tiptoi-sync
+
+Android app (Capacitor + SolidJS) for searching, downloading, and syncing tiptoi
+books onto a tiptoi pen. All book search/download and pen file access happens
+**natively on-device** — there is no backend server in this repo despite what
+`README.md`'s architecture diagram describes (that README is stale/aspirational
+for a self-hosted server variant; the current implementation is Android-only).
+
+## Repository layout
+
+- `client/` — SolidJS + Vite PWA/webview UI (workspace root's actual app code).
+  - `src/api.ts` — all "business logic": scraping Ravensburger's search API/HTML
+    for `.gme` download links, orchestrating download + sync, calling the
+    native plugin.
+  - `src/native/TiptoiPlugin.ts` + `src/native/DevPlugin.ts` — TypeScript
+    interfaces for Capacitor native plugins (`registerPlugin`). Any change to
+    the native Kotlin plugin's method signatures must be mirrored here.
+  - `src/pages/` — `ScanPage.tsx` (barcode/text search) and
+    `DownloadsPage.tsx` (library + pen sync UI).
+  - `android/` — Capacitor Android project, **checked into the repo** (not
+    generated on demand). `android/app/src/main/java/com/tiptoisync/app/`
+    contains the actual native implementation:
+    - `TiptoiPlugin.kt` — SAF (Storage Access Framework) directory picker for
+      the pen, listing/copying/deleting `.gme` files on the pen, downloading
+      GME/cover files into app-private storage via `HttpURLConnection`.
+    - `DevPlugin.kt` — enables Capacitor live-reload against a Vite dev server
+      (see `DEV_URL` below).
+- `Dockerfile.android`, `build-apk.sh` — reproducible APK build via
+  Docker/Podman (no local Android SDK needed). Output APK lands in
+  `apk-output/tiptoi-sync.apk`.
+
+## Build & dev commands
+
+Run from repo root (workspace uses `bun`):
+
+```bash
+bun install                 # installs client workspace deps
+bun run dev                  # starts Vite dev server (client) with --host
+bun run build                 # tsc -b && vite build for client
+bun run cap:sync              # copies web build into android/ project
+bun run cap:android            # builds & runs on connected device/emulator
+```
+
+Equivalent scripts also exist directly in `client/package.json` (`bun --cwd
+client run <script>` or `cd client && bun run <script>`).
+
+There are no unit/integration tests or linters configured in this repo — only
+TypeScript's compiler (`tsc -b`, run as part of `build`) enforces correctness
+on the client. Validate client changes with `bun run build` from the repo
+root, or `cd client && bunx tsc -b --noEmit` for a faster type-only check.
+
+### Building the Android APK
+
+```bash
+./build-apk.sh
+```
+
+Wraps a multi-stage `Dockerfile.android` build (Bun + Android SDK + Gradle)
+using Podman or Docker, with `--no-cache` to avoid stale layers. No local
+Android SDK/Gradle install required. Result: `apk-output/tiptoi-sync.apk`.
+
+### Live-reload against Vite dev server on a device
+
+```bash
+DEV_URL=http://<host-ip>:5173 bun run cap:android
+```
+
+`client/capacitor.config.ts` reads `DEV_URL` and switches Capacitor's webview
+to load from the dev server (with `cleartext: true`) instead of the bundled
+`dist/` output. `DevPlugin.kt`/`DevPlugin.ts` support activating/deactivating
+this from within the running app (see `DevMenu.tsx`, triggered by 5 taps on
+the app title within 2 seconds — see `App.tsx`).
+
+## Key conventions
+
+- **UI copy is German.** Keep user-facing strings, comments in `api.ts`, and
+  section-divider comments (e.g. `// ── Suche ──...`) in German to match the
+  existing style.
+- **Native plugin contract**: TypeScript interfaces in `src/native/*.ts` must
+  stay in sync with `@PluginMethod`/`@CapacitorPlugin` definitions in the
+  corresponding Kotlin files — there's no code generation, it's manually kept
+  in sync.
+- **All book search scraping logic lives in `api.ts`** (regex-based HTML
+  parsing of Ravensburger's site, HTML entity decoding). If Ravensburger
+  changes their markup, this is the place to fix it.
+- Filenames for downloaded books derive from the last path segment of the GME
+  URL (decoded, `.gme` stripped); covers reuse the same base name with the
+  cover's own extension.
+- `syncAll` in `api.ts` is the single source of truth for "what needs
+  copying to the pen": it diffs local downloads against `listPenFiles`.