Add release workflow publishing builds to Gitea

Build, verify and publish dist/<id>.plugin to the Releases tab on every
push to main. Nothing is plugin-specific: the id and version are read
from plugin.json, so the workflow keeps working once this template is
renamed into a real plugin.

The version in plugin.json decides what happens: a new version creates
tag v<version> and a new release, while an unchanged version rebuilds the
existing release and replaces its attachment. The tag is never moved, so
it keeps pointing at the commit that first introduced that version, but
the release notes are refreshed to name the commit the build came from.

The upload is gated on verify_bundle.py, so a bundle that fails offline
verification is never published. dist/ stays gitignored and the artifact
is always built by CI rather than committed.

README.md

@@ -40,6 +40,8 @@ tools/
   bundle.py         compiles plugin.json + src/ into dist/<id>.plugin
   devclient.py      speaks the on-device dev-server protocol (127.0.0.1:42690)
   verify_bundle.py  offline harness that proves a built bundle behaves correctly, no phone needed
+  release.py        publishes a built bundle to a Gitea release (used by CI)
+.gitea/workflows/   CI that builds, verifies and publishes the .plugin to Releases
 scripts/            bash automation for the ADB debug loop (see below)
 docs/sdk-notes.md   condensed SDK API surface gathered from the official docs
 ```
@@ -91,6 +93,41 @@ standard `ANDROID_SERIAL` env var for device selection.
 - `scripts/fetch-sdk-stubs.sh [--beta]` — downloads the latest SDK type stubs into `stubs/`
   for editor autocomplete.
 
+## Publishing a release
+
+`.gitea/workflows/release.yml` builds, verifies and publishes the `.plugin` to the repo's
+Releases tab on every push to `main`. `dist/` is gitignored, so the artifact is always built
+by CI rather than committed. Nothing in the workflow is plugin-specific — it reads the id and
+version straight out of `plugin.json`, so it keeps working after you rename the plugin.
+
+The `version` field in `plugin.json` is the single source of truth:
+
+| Push to `main` with… | Result |
+| --- | --- |
+| a new `version` | creates tag `v<version>` and a new release |
+| the same `version` | rebuilds the existing release, replacing its attachment |
+
+So every push leaves a downloadable build attached to the current version, and bumping
+`version` is what cuts a new release. Pushing a `v*` tag by hand still works and uses that
+tag verbatim, as does a manual run (Actions → Publish plugin → Run workflow).
+
+Every path runs `--check`, builds with `--release`, and gates the upload on
+`verify_bundle.py`, so a bundle that fails verification is never published. A rebuild
+replaces the attachment rather than piling up duplicates, and refreshes the release notes to
+name the commit it came from. The tag itself is never moved: it keeps pointing at the commit
+that first introduced that version.
+
+Authentication uses `secrets.API_TOKEN`, an organisation-level Actions secret holding a user
+token with the `write:repository` scope (which covers releases). Set it once under
+**Org → Settings → Actions → Secrets** and every repo in the organisation inherits it; a
+repo-level secret of the same name takes precedence if one repo ever needs different
+credentials.
+
+If you would rather not manage a token, Gitea also injects a per-job `secrets.GITEA_TOKEN`
+that can create releases in its own repo — swap the `env:` line in the workflow and drop the
+org secret. It is scoped to the single job and expires with it, so it is the safer default;
+`API_TOKEN` is what you want when publishing needs to reach beyond this repo.
+
 ## Writing your own plugin
 
 1. Edit `plugin.json` (id, name, description, etc.).