Add spec.md: goal, limits and rules for working on the project

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

spec.md

@@ -0,0 +1,59 @@
+# Plexamp Lite (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 Plexamp-style Plex music player for the Samsung Galaxy Mini that keeps playing reliably at home, away and
+over a Bluetooth speaker.
+
+## Target and hard limits
+
+- Samsung Galaxy Mini GT-S5570: Android 2.2/2.3 (API 8), 240×320 ldpi, 600 MHz ARMv6, 384 MB RAM; any 2.2+
+  phone.
+- Native Java (this app uses XML layouts), no libraries beyond the bundled Bouncy Castle TLS.
+- Galician by default, English in Settings. All text in `tools/strings.py`, which generates
+  `res/values*/strings.xml`. The connection log stays in English.
+- Plays MP3/AAC/Vorbis directly; FLAC, ALAC and the rest are transcoded to MP3 by the server.
+
+## Current scope (1.13)
+
+- Sign in with a plex.tv/link PIN (or a manual address + token). Owned and shared servers and libraries.
+- Connection picking: last good one first, then LAN HTTP, LAN HTTPS (`plex.direct`), remote HTTPS, Relay
+  (capped at 192 kbps). Secure addresses tried one at a time; re-checked on network changes.
+- Bundled TLS 1.2/1.3 with session resumption; a loopback `StreamProxy` feeds the media player.
+- Quality per network (home, away, Bluetooth cap), read-ahead of the next two tracks, stall and failure
+  recovery (re-pick, then download first), resume after short Bluetooth drop-outs.
+- Home radios and shelves, Artists/Albums/Playlists, Search, artist/album/playlist pages, Now Playing, Up
+  Next queue (survives restarts), sleep timer, love, downloads to SD card with offline play reporting.
+- Headset and Bluetooth buttons; pauses for calls and unplugging. Plays reported to Plex.
+
+## Out of scope
+
+- Gapless playback and notification playback buttons (Android 2.x can't), video, photos.
+
+## Must not break
+
+- Package `com.minamp` and `signing/minamp.keystore` (password `minamp123`): updates install over Minamp.
+- Signing: `tools/signapk.py` (classic SignApk v1); never `jarsigner`.
+- `src/com/minamp/net/` is the origin of `tlskit`; keep the two in step (change `../tlskit`, reinstall).
+- This repo's `tools/setup_toolchain.sh`, `make_roots.py` and `signapk.py` prepare the toolchain all the
+  Galaxy Mini apps use: changes there affect every app.
+- Installs to internal storage (SD-card installs get killed during USB sharing).
+
+## Code map
+
+`PlayerService` (playback, recovery) · `PlayQueue` · `Downloads` · `plex/` (`Plex`, `Server`, `Library`,
+`Item`) · `net/` (`Http`, `CertVerifier`, `StreamProxy`, `Threads`, `DiagLog`) · activities Home, Browse,
+NowPlaying, Queue, Search, Setup, Downloads.
+
+## Build, test, release
+
+- `tools/setup_toolchain.sh` once, then `./build.sh` → `build/PlexampLite.apk`.
+- Tests on the desktop JVM: `PlexTest` with `test/mock_plex.py`, `QueueTest`, `PreferHomeTest` with
+  `test/identity_server.py`, `NetTest`, `HandshakeProfile`.
+- Release: raise `versionCode`/`versionName`, build, add `changes` in `../tenda-lite/repo/apps.json`, commit
+  and push, `../tenda-lite/repo/publish.sh`.
+- Siblings for iPod, Mac and Linux (`plexamp-lite-ios`, `-mac`, `-linux`) share behaviour; fixes are often
+  backported between them.