docs: the README's aims, developer setup and releases

The README opens with what the app aims at: creating, sharing and
collaborating on study material, FSRS for retention, study material
organised with its external references, offline-first, and a transparent
stack anyone can host.

"Setting up" lists what developers need: Flutter as CI pins it, with
Flutter's own guide per platform; the Serverpod CLI; the Linux packages,
with what each plugin needs them for; Developer Mode on Windows, and why;
no Docker for development; Python for the scripts in tool/.

"Releases" says where releases are published, how to check a download
(the signed checksums, the APK certificate's fingerprint), how versions
are numbered, and how a maintainer makes one with tool/release.sh.

AGENTS.md: Windows needs Developer Mode for Flutter's plugin links too,
not only for pdfrx's build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

AGENTS.md

@@ -156,5 +156,5 @@ A spaced-repetition learning app: studysets of flashcards, reviewed on an FSRS s
 - **Session logs are not persisted** (`persistentEnabled: false` in every run mode) for privacy. Don't re-enable them.
 - **Secrets** live in `halkyon_learn_server/config/passwords.yaml` (git-ignored). Never change `serverSideSessionKeyHashPepper`: it would sign everyone out, and anonymous accounts can't sign back in.
 - **Checks on a device** live in `halkyon_learn_flutter/integration_test/` and run by hand, never in `tool/check.sh` or CI: `flutter test integration_test/<file> -d <device>`. `pdf_engine_test.dart` checks the real PDF engine (on the Linux desktop too), `youtube_player_test.dart` the embedded YouTube player (Android). Never on the emulator from an agent session: it takes the editor down with it.
-- **Windows builds need Developer Mode** (pdfrx's build makes symbolic links). PDFium itself comes with the build as a Dart native asset.
+- **Windows builds need Developer Mode**: building makes symbolic links (Flutter links each plugin's native code into the build, and pdfrx's build does too), which Windows lets ordinary users make only in Developer Mode. PDFium itself comes with the build as a Dart native asset.
 - **Linux builds need** `libwebkit2gtk-4.1-dev`, `libsecret-1-dev`, and for sounds (`audioplayers`) `libgstreamer1.0-dev` and `libgstreamer-plugins-base1.0-dev`. If a Linux build tries to install to `/usr/local`, the CMake cache is stale: delete `build/linux`.

README.md

@@ -1,7 +1,11 @@
 # Halkyon Learn
 
-A spaced-repetition learning app: studysets of flashcards with rich text, studied offline
+Halkyon Learn is for creating, sharing and collaborating on study material. It schedules
-on every device and synced between a person's devices. Anyone can run an instance.
+flashcards with [FSRS](https://github.com/open-spaced-repetition) to strengthen
+retention, and organises study material together with the external references it draws
+on. It is offline-first: everything works on the device, without a connection. And the
+whole stack is transparent: the app, the server and everything needed to host an
+instance are published, so anyone can see how an instance works and run their own.
 
 - **Offline first.** Each device keeps its own database and syncs in the background
   (`serverpod_offline_sync`). Edits made on two devices while offline are never lost:
@@ -24,14 +28,41 @@ Targets: Linux, Windows, macOS, Android and iOS. There is no web build.
 | `halkyon_learn_client` | The client, generated from the server's models | AGPL-3.0-or-later |
 | `halkyon_learn_flutter` | The app (`app.halkyon.learn`) | AGPL-3.0-or-later |
 
-## Running it locally
+## Setting up
 
-You need Flutter (Dart v3.13 or later) and the Serverpod CLI v4.0.3
+- **Flutter v3.47.5**, the version CI uses (`FLUTTER_VERSION` in
-(`dart install serverpod_cli@4.0.3`). Linux builds also need `libwebkit2gtk-4.1-dev` and
+  `.forgejo/workflows/ci.yaml`). Set up each platform you build for with Flutter's own
-`libsecret-1-dev`. The rich-text editor comes from our fork of AppFlowy Editor
+  guides: [Linux](https://docs.flutter.dev/platform-integration/linux/setup),
+  [Windows](https://docs.flutter.dev/platform-integration/windows/setup),
+  [Android](https://docs.flutter.dev/platform-integration/android/setup),
+  [macOS](https://docs.flutter.dev/platform-integration/macos/setup),
+  [iOS](https://docs.flutter.dev/platform-integration/ios/setup).
+- **The Serverpod CLI v4.0.3**: `dart install serverpod_cli@4.0.3`. Pass `--no-analytics`
+  to every call; otherwise it reports the commands run to Serverpod.
+- **Linux**, on top of Flutter's packages, the libraries of three plugins: WebKitGTK
+  (pulled in by the sign-in package), libsecret (keeps the session) and GStreamer
+  (plays sounds). On Debian or Ubuntu, Flutter's and these together:
+
+  ```sh
+  sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev libstdc++-12-dev \
+    libwebkit2gtk-4.1-dev libsecret-1-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
+  ```
+
+- **Windows** needs Developer Mode (Settings › System › For developers): building makes
+  symbolic links, as Flutter links each plugin's native code into the build and the PDF
+  engine's build does too, and Windows lets ordinary users make them only in Developer
+  Mode.
+- **No Docker** for development: `serverpod start` and the server's tests run an embedded
+  PostgreSQL. Docker Compose is only for running an instance (below).
+- **For the scripts in `tool/`**: Python 3 (`tool/snap_icon.py` also needs Pillow,
+  `python3-pil`), and for releases what [Releases](#releases) lists.
+
+The rich-text editor comes from our fork of AppFlowy Editor
 ([project-halkyon/appflowy-editor](https://code.halkyon.app/project-halkyon/appflowy-editor)),
 which `flutter pub get` fetches by itself.
 
+## Running it locally
+
 The server's secrets live in `halkyon_learn_server/config/passwords.yaml`, which is never
 committed. In a fresh clone, create it with a `development` and a `test` section, each
 holding `database`, `serverSideSessionKeyHashPepper` and `serviceSecret` (for example from
@@ -76,6 +107,30 @@ the CI runner described in `deploy/runner/`, deploys only commits signed by a ke
 `deploy/allowed-signers`. It backs up its database every hour, off-site and encrypted;
 [`deploy/backups.md`](deploy/backups.md) says how to set that up and how to restore.
 
+## Releases
+
+Releases are published on [code.halkyon.app](https://code.halkyon.app/project-halkyon/halkyon_learn/releases)
+and, for Linux, in the Snap Store (`halkyon-learn`). Their builds connect to
+learn.halkyon.eu, the project's instance.
+
+- **Checking a download:** `SHA256SUMS` lists the checksum of every file, signed with the
+  maintainer's GPG key (`SHA256SUMS.asc`). The APK is signed with the app's key, whose
+  certificate has the SHA-256
+  `27:E2:43:FC:BD:C8:26:FF:98:AB:7D:BB:10:43:6C:98:C3:BE:A2:4B:2A:01:5E:94:E4:CF:C7:D1:FC:2A:00:6C`
+  (`apksigner verify --print-certs` shows it).
+- **Versions** are `version` in `halkyon_learn_flutter/pubspec.yaml`,
+  `<major>.<minor>.<patch>+<build>`. Every release raises the build number: Android only
+  installs a higher one over an older, and the server tells apps below the build it
+  supports to update.
+- **Making one** is for maintainers, on their own machine and never in CI:
+  `tool/release.sh vX.Y.Z`. Its header says what it needs (the signed tag, the app's
+  key, a Forgejo token, `snapcraft login`). It builds the APK and the snap
+  (`snap/snapcraft.yaml`, built in LXD; its icon comes from `tool/snap_icon.py`), checks
+  both, signs the checksums and publishes everything. Besides Flutter and the Android
+  SDK, it uses snapcraft with LXD, a JDK (keytool), GnuPG, curl, jq, unzip and
+  squashfs-tools. Release builds made without the app's key are signed with the debug
+  key and can't update a released app.
+
 ## More
 
 - [`AGENTS.md`](AGENTS.md): how the code is organised and the rules it follows.