diff --git a/spec.md b/spec.md
new file mode 100644
index 0000000..ec6ae30
--- /dev/null
+++ b/spec.md
@@ -0,0 +1,52 @@
+# Podlite (Android) — spec
+
+The short contract for working on this app. `README.md` is the user guide; this file says what the app is
+for, what limits it lives within, and what must not break.
+
+## Goal
+
+A small Audiobookshelf podcast client for the Samsung Galaxy Mini whose progress stays in sync with the
+server and other apps.
+
+## Target and hard limits
+
+- Samsung Galaxy Mini GT-S5570 and other Android 2.2+ phones (API 8), 240×320 ldpi.
+- Native Java, no libraries beyond the bundled TLS stack. All sizes in `res/values/dimens.xml`.
+- Galician interface; warm dark colours with an amber accent (from the radio icon).
+
+## Current scope (1.11)
+
+- Login with user/password (refreshes 2.26+ short-lived tokens; older servers' long-lived token) or an API key.
+- HTTP on the LAN; bundled TLS 1.2 for `https://` (Mozilla roots); other certificates shown by fingerprint,
+  trusted once (trusting the issuing CA so renewals work), forgettable in Settings.
+- Loopback stream proxy for HTTPS, forwarding seeks with a fresh token per request.
+- Tabs: Latest (continue listening + newest), Shows, Saved (SD-card downloads, Wi-Fi only by default).
+- Player: skip back/forward (amounts in Settings), seek, show notes, sleep timer, mark played, close.
+- Progress sync every 15 s and on pause; offline positions sent later.
+- Headset buttons; pauses for calls and unplugging.
+
+## Out of scope
+
+- Audiobooks, playback speed (Android 2.x can't), HLS/transcoded streams (so no Opus).
+
+## Must not break
+
+- An episode only counts as played within a minute of its real end; drop-outs and cut files are retried or
+  reported, never marked played. A stall of 12 s is reported.
+- Package `com.miniabs` and `miniabs.keystore` (password `miniabs`): updates install over MiniABS.
+- `src/com/miniabs/net/` is a copy of `tlskit`: change it in `../tlskit` and reinstall.
+- Installs to internal storage.
+
+## Code map
+
+`Api` · `PlayerService` · `StreamProxy` · `DownloadService` / `Downloads` · `Trust` / `TrustPrompt` · `Prefs` ·
+activities Home, Podcast, Player, Login, Settings · `net/` tlskit · `tools/make_icons.py`, `translate_gl.py`.
+
+## Build, test, release
+
+- `ANDROID_JAR=/path/to/android-8/android.jar ./build.sh` (JDK, aapt, dx, zipalign, apksigner, `BC_SRC`).
+- `JSON_JAR=… test/run_tests.sh`: API, JSON, progress, HTTPS trust and proxy against `test/mock_abs.py`,
+  with good, expired, wrong-host, forged and self-signed certificates (`test/make_pki.sh`).
+- Release: raise `versionCode`/`versionName`, build, add `changes` in `../tenda-lite/repo/apps.json`, commit
+  and push, `../tenda-lite/repo/publish.sh`.
+- Siblings: `podlite-ios`, `podlite-mac`; behaviour fixes are backported between them.