Update build procedures and documentation

.gitea/workflows/build.yml

@@ -1,9 +1,11 @@
 name: build
 
 on:
-  push:
-    branches: [dev, main]
-  pull_request:
+  # Manual only for now. Select the branch to build when dispatching:
+  #   main -> APP_VERSION is the current git tag
+  #   dev  -> APP_VERSION is the current commit hash
+  # Both branches bake the portal API key from secrets.
+  workflow_dispatch:
 
 jobs:
   nix-build:
@@ -11,11 +13,13 @@ jobs:
     steps:
       # actions/checkout@v4 is unreliable on host-mode runners (its files are
       # copied into the workspace instead of the repo), so clone explicitly.
+      # A full clone (no --depth) is required so `git describe --tags` on main
+      # resolves the real nearest tag instead of falling back to a hash.
       - name: Checkout
         run: |
           rm -rf ./* ./.[!.]* 2>/dev/null || true
           git config --global http.extraheader "Authorization: token ${{ github.token }}"
-          git clone --depth 1 --branch "${{ gitea.ref_name }}" \
+          git clone --branch "${{ gitea.ref_name }}" \
             "${{ gitea.server_url }}/${{ gitea.repository }}.git" .
           test -f flake.nix
           git log --oneline -1
@@ -26,12 +30,37 @@ jobs:
           ls -la
           git rev-parse --show-toplevel 2>&1 || true
           git remote -v 2>&1 || true
+          git describe --tags --always 2>&1 || true
           test -f flake.nix && echo "flake.nix present" || echo "NO flake.nix"
 
+      # Compute the version string baked into the binary's Home footer:
+      # main reports the git tag, dev reports the commit hash fingerprint.
+      # The key stays in the build step's environment (never echoed).
+      - name: Compute version
+        id: version
+        run: |
+          if [ "${{ gitea.ref_name }}" = "main" ]; then
+            APP_VERSION="$(git describe --tags --always)"
+          else
+            APP_VERSION="$(git rev-parse --short HEAD)"
+          fi
+          echo "APP_VERSION=$APP_VERSION" >> "$GITHUB_ENV"
+          echo "Branch: ${{ gitea.ref_name }} -> APP_VERSION=$APP_VERSION"
+          if [ -n "${{ secrets.RWT_API_KEY }}" ]; then
+            echo "API key: provided via secret RWT_API_KEY"
+          else
+            echo "API key: NOT set (build proceeds without an Authorization header)"
+          fi
+
       # checks is keyed per-system (checks.<system>.default); nix build's
       # #attr shorthand can't resolve it, so resolve the current system inline.
+      # --impure lets the flake read APP_VERSION/API_KEY via builtins.getEnv
+      # (pure evals always get the package defaults). The offline test suite
+      # runs in the package's checkPhase.
       - name: Build + offline test suite
-        run: nix build -L ".#checks.$(nix eval --impure --raw --expr 'builtins.currentSystem').default"
+        env:
+          API_KEY: ${{ secrets.RWT_API_KEY }}
+        run: nix build -L ".#checks.$(nix eval --impure --raw --expr 'builtins.currentSystem').default" --impure
 
       - name: Live portal tests
         if: ${{ secrets.RWT_LIVE_API_KEY != '' }}