fix ots

docs/production-builds.md

@@ -62,6 +62,20 @@ All secrets live under **Repository → Settings → Actions → Secrets**.
 | `KADENCE_KEY_ALIAS` | `android-release.yml` | The key alias, normally `kadence` |
 | `KADENCE_KEY_PASSWORD` | `android-release.yml` | The key password |
 
+All four `KADENCE_KEY*` secrets are needed for a release. Before uploading the
+base64 blob, check that the alias and passwords actually open the file:
+
+```bash
+keytool -list \
+  -keystore your-release.keystore \
+  -storepass "$KADENCE_KEYSTORE_PASSWORD" \
+  -alias "$KADENCE_KEY_ALIAS"
+```
+
+Then produce the secret with `base64 -w0 your-release.keystore`. The workflow
+fails early and names any missing signing secret, instead of waiting for
+`packageRelease` to report a keytool error.
+
 The workflow uses Gitea's built-in `GITEA_TOKEN` to attach the APK to a tagged
 release. That token is supplied by Actions; it is not one of the secrets above.
 
@@ -392,8 +406,10 @@ version code and rebuild.
 The run page in Gitea is the simplest route: **Actions → run → Artifacts**.
 For a tagged release, the attached asset is under **Releases**.
 
-With a personal access token, the API works too. Listing the artifacts of the
-latest successful `android` run:
+With a personal access token, the API works too. Gitea's artifacts API only
+lists artifacts uploaded through the v4 artifact protocol, so the workflow uses
+`https://gitea.com/actions/gitea-upload-artifact@v4`. Listing the artifacts of
+the latest successful `android` run:
 
 ```bash
 TOKEN=...  # a Gitea token with repository read access
@@ -434,8 +450,10 @@ copy.
 | `Cannot connect to the Docker daemon` in `docker.yml` | The job container does not have the host socket; check `docker_host` and `valid_volumes` in `deploy/act-runner.yaml` |
 | The Docker push returns 401 | `REGISTRY_TOKEN` is a job token or a PAT without `package:write`, or the username does not match the token |
 | Android build fails before Gradle starts | The SDK install failed; check `android/ci/install-sdk.sh` and the cache key. A cold cache can take several minutes |
+| `Failed to read key  from store ...: keystore password was incorrect` | The alias or a password secret is empty or wrong; the blank before `from` is the alias. All four `KADENCE_KEY*` secrets are required. Verify locally with `keytool -list` before re-encoding the keystore |
 | The APK is debug-signed despite the keystore secrets | At least one of `KADENCE_KEYSTORE_BASE64`, `KADENCE_KEYSTORE_PASSWORD`, `KADENCE_KEY_ALIAS`, `KADENCE_KEY_PASSWORD` is missing or wrong. With `KADENCE_REQUIRE_SIGNING` the job should have failed; fix the secret rather than shipping it |
 | `kadence-release-apk` is missing from the run | The build failed before the upload step, or the artifact has expired |
+| The artifact API returns `total_count: 0` although the job uploaded the files | The workflow used `actions/upload-artifact@v3`; Gitea 1.24+ only exposes v4-protocol artifacts through `/actions/artifacts`. Use `https://gitea.com/actions/gitea-upload-artifact@v4` and run the build again |
 | The tag build cannot attach the APK to a release | The tag was pushed but no release exists yet, or the built-in `GITEA_TOKEN` lacks permission. Create the release, or check the repository's Actions token permissions |
 | A tag push did not start a workflow | The tag does not match `v*`, or it was created locally and never pushed: `git push origin v0.2.0` |
 | The deployment still runs old code after a pull | `docker compose up` rebuilt the local checkout. Use `--no-build` and pin `KADENCE_IMAGE` |