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,41 @@
+# tlskit — spec
+
+The short contract for working on the shared HTTP/TLS client. `README.md` explains its use; this file says
+what it promises to the apps that copy it.
+
+## Goal
+
+Let Android 2.2/2.3 apps reach modern `https://` servers (TLS 1.2, today's roots, SNI), which the
+system's own TLS 1.0 stack can't.
+
+## Users
+
+Copied into: Plexamp Lite, Podlite, Noticias Lite, Calendar Lite (by hand, under
+`android/org/gingercal/net`), AcasaLite, Tenda Lite and WikipeLite. The apps carry copies, not a dependency.
+
+## What it provides
+
+- `net/Http.java`: HTTP/1.1 on Bouncy Castle TLS 1.2 (renamed `com.minamp.bc`), keep-alive pooling, session
+  resumption, chunked bodies.
+- `net/CertVerifier.java`: host name, validity dates, chain up to a bundled Mozilla root (trust anchors must
+  be CAs); optionally one pinned leaf certificate (SHA-256), with the fingerprint shown to the user. Untrusted
+  errors carry the chain.
+- `net/AssetRoots.java` + `roots/`: Mozilla's roots as `assets/roots/<sha1(subject)>-<n>.der`; loaded roots
+  are kept in memory and a failed read is retried.
+- `net/Threads.java`: threads with a 256 KB stack; network work must run on one.
+- `net/DiagLog.java`: connection log with tokens removed from URLs.
+
+## Must not break
+
+- Must run on Dalvik for API 8: no newer Java or Android APIs.
+- Must not clash with the old Bouncy Castle inside Android (keep the `com.minamp.bc` rename).
+- Never log tokens or passwords.
+- A change here is not done until it has been reinstalled into every app above and each one rebuilt
+  (and released through Tenda).
+
+## Workflow
+
+- `./install.sh <app dir> <java package>` copies `net/` into the app's package and `roots/` into its `assets/`.
+- Bouncy Castle sources come from Plexamp Lite's `tools/setup_toolchain.sh` (`~/android-toolchain/bcsrc`);
+  roots are regenerated with Plexamp Lite's `tools/make_roots.py`.
+- Test: `test/KitTest.java` on a desktop JVM against real FreshRSS, Nextcloud and Audiobookshelf servers.