Update build procedures and documentation

README.md

@@ -133,7 +133,12 @@ cmake --build build
 If `APP_VERSION` is left unset the footer falls back to the project version
 from `CMakeLists.txt` (`project(... VERSION ...)`); a build that defines no
 version at all shows `unknown`. The Nix build sets `APP_VERSION` automatically
-to the flake package version, so `nix build` needs no extra flags.
+to the flake package version, so a plain `nix build` needs no extra flags.
+With `--impure` the flake instead reads the `APP_VERSION` / `API_KEY`
+environment variables — this is how CI injects the version and portal key
+(see the CI note under *Common Pitfalls*). Pure evals always get the package
+defaults, because `builtins.getEnv` cannot see the environment in pure
+evaluation mode.
 
 #### Portal API key
 
@@ -151,7 +156,8 @@ cmake --build build
 
 Rotate the key by building with a new value and shipping the new binary. The
 Nix package accepts the same value via `callPackage ./nix/package.nix {
-apiKey = "…"; }`; the flake itself never embeds one.
+apiKey = "…"; }`, or via the `API_KEY` environment variable with
+`nix build --impure`; the flake itself never embeds one.
 
 #### Version + API key in one configure
 
@@ -179,6 +185,17 @@ nix build .#packages.x86_64-linux.default  # needs a Linux machine/builders
 nix build .#packages.aarch64-linux.default
 ```
 
+To bake in a custom version and/or portal key, build impurely — the flake
+reads `APP_VERSION` and `API_KEY` from the environment on impure evals:
+
+```sh
+APP_VERSION="1.2.3" API_KEY="$PORTAL_API_KEY" nix build --impure .#default
+```
+
+A pure `nix build` always uses the package defaults (`0.1.0`, no auth header)
+even if those variables are set in your shell, because pure evaluation cannot
+see the environment. CI uses `--impure` to inject them.
+
 `nix build` runs the full offline test suite in its `checkPhase`; the
 live-portal test binaries (`test_api_client`, `test_license_service`) are
 excluded. `nix flake check` builds the package and therefore also runs the
@@ -610,6 +627,12 @@ status to decide which page to show.
 - `build/` is gitignored. Do not commit build artifacts.
 - Use the Nix dev shell or ensure SDL3 is installed for building.
 - CI uses Gitea Actions on a self-hosted host runner (`build-server`); the
-  workflow is `.gitea/workflows/build.yml`.
+  workflow is `.gitea/workflows/build.yml`. It is **manual-only**
+  (`workflow_dispatch`) — pick the branch when dispatching. `main` builds bake
+  the current git tag as `APP_VERSION`; `dev` builds bake the current commit
+  hash. Both pass the portal key from the `RWT_API_KEY` secret and build with
+  `nix build --impure` (which lets the flake's env injection work). The
+  offline test suite runs in the package's `checkPhase`; the live portal tests
+  run from `nix develop` when the `RWT_LIVE_*` secrets are set.
 - Asset tests (`test_assets`) must pass before committing -- they catch missing
   fonts and images that would break the app at runtime.