docs: rewrite README with comprehensive toolchain usage guide

build.yml

@@ -0,0 +1,79 @@
+name: build-release
+
+# Drop this into any Android app repo at .gitea/workflows/build.yml
+# It runs the release build inside the pinned toolchain image and publishes
+# the signed artifact. Instrumented tests are NOT run here — by design,
+# prod builds are promotions of code already tested in Dev.
+
+on:
+  push:
+    tags: ["v*"]          # build prod artifacts on version tags
+  workflow_dispatch:
+    inputs:
+      gradle_task:
+        description: "Release task"
+        type: choice
+        default: assembleRelease     # APK. Use bundleRelease for a Play AAB.
+        options: [assembleRelease, bundleRelease]
+
+env:
+  # Pin the toolchain. Bump deliberately when you roll forward.
+  BUILDER_IMAGE: git.helu.ca/r/android:2026.06
+  # Default task for tag-triggered builds (workflow_dispatch overrides via input)
+  DEFAULT_TASK: assembleRelease
+
+jobs:
+  build:
+    runs-on: [self-hosted, arm64]
+    container:
+      image: git.helu.ca/r/android:2026.06
+      credentials:
+        username: ${{ gitea.actor }}
+        password: ${{ secrets.GITEA_TOKEN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Resolve gradle task
+        id: task
+        run: |
+          TASK="${{ inputs.gradle_task }}"
+          [ -z "$TASK" ] && TASK="${DEFAULT_TASK}"
+          echo "task=$TASK" >> "$GITHUB_OUTPUT"
+
+      # --- Signing ---------------------------------------------------------
+      # Store the keystore as a base64-encoded Gitea Actions secret and the
+      # passwords as separate secrets. Nothing sensitive lives in the repo
+      # or the image. Decode at job time into a path Gradle reads.
+      #
+      # Create the base64 secret yourself with:
+      #   base64 -w0 release.keystore   (copy output into secret KEYSTORE_BASE64)
+      #
+      # Reference KEYSTORE_PASSWORD / KEY_ALIAS / KEY_PASSWORD from your
+      # signingConfig (or via -Pandroid.injected.signing.* as below).
+      - name: Decode keystore
+        run: |
+          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > "$RUNNER_TEMP/release.keystore"
+
+      - name: Build release
+        run: |
+          ./gradlew --no-daemon ${{ steps.task.outputs.task }} \
+            -Pandroid.injected.signing.store.file="$RUNNER_TEMP/release.keystore" \
+            -Pandroid.injected.signing.store.password="${{ secrets.KEYSTORE_PASSWORD }}" \
+            -Pandroid.injected.signing.key.alias="${{ secrets.KEY_ALIAS }}" \
+            -Pandroid.injected.signing.key.password="${{ secrets.KEY_PASSWORD }}"
+
+      # Collects whichever artifact the task produced — apk or aab.
+      - name: Collect artifact
+        run: |
+          mkdir -p out
+          find app/build/outputs -type f \( -name "*-release.apk" -o -name "*-release.aab" \) \
+            -exec cp {} out/ \;
+          ls -l out
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-artifacts
+          path: out/*
+          if-no-files-found: error