docs: cut GitHub releases so the push mirror cannot delete them

GitHub is a pruning push mirror of Gitea, so a tag created by
"gh release create" belongs to no upstream ref and disappears on the next
synchronisation, orphaning the release and its archives. Document the order
that survives it: push the tag to Gitea, wait for the mirror, verify the tag
on GitHub, publish with --verify-tag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/CHANGELOG.md

@@ -52,6 +52,45 @@ dragged.**
   row's edge — does not, so the gap collapsed to about a pixel. The Theme row
   now keeps the same gap the checkbox rows have.
 
+**Documentation:**
+
+- The **README** describes the application that exists. Its `gosentry.json`
+  sample was three keys short of what the app writes on first run, which made
+  the one file the user is invited to hand-edit the least accurate thing in the
+  document; it is now the real default, with each key explained — including why
+  a zero timeout is written out and an unset one is not. The feature list has
+  caught up with the run timeout, the theme, the compact job list, and the
+  per-job overlap and timeout overrides the job dialog has always offered.
+- **`docs/DEVELOPMENT.md`** is ordered as stack, external libraries, run from
+  source, build, release, CI, behind a two-level table of contents, instead of
+  opening with MSYS2 setup and burying "Run From Source" mid-document. The
+  library table gains versions and licenses, the `package-*` scripts are
+  documented for the first time and labelled by OS, and the Codeberg
+  `RELEASE_TOKEN` note now states the failure mode rather than leaving it to be
+  inferred from a red job: build and packaging succeed, the upload step fails on
+  authentication and takes the job with it, leaving a published release with no
+  assets. The Project Layout section is gone — it duplicated ARCHITECTURE's
+  package map and had drifted out of date.
+- **Cutting a GitHub release now documents the push mirror it has to survive.**
+  GitHub is a pruning push mirror of Gitea, so `gh release create` creating the
+  tag itself produces a tag Gitea does not know about, which the next
+  synchronisation deletes — orphaning the release and taking its uploaded
+  archives with it, without a single failed step to point at. The procedure is
+  push the tag to Gitea, wait for the mirror, verify the tag on GitHub, then
+  publish with `--verify-tag`.
+- **`docs/TESTS.md`** matches the suite it indexes again. It listed 130 tests
+  against 170 in the tree, omitted four test files entirely, and named two tests
+  that no longer exist. Every test function now appears exactly once, under the
+  file it actually lives in.
+- **`docs/ARCHITECTURE.md`** no longer draws the UI calling the autostart
+  manager directly — it does not, and `src/ui` holds no reference to that
+  package — and `platform/desktop` is described by what it does (the XDG desktop
+  entry and icon) rather than as a display-scale helper.
+- The **~250-line file guideline** is stated as the target it is, with the six
+  files currently over it recorded as a `docs/ROADMAP.md` item. They are to be
+  split in one pass during the next whole-project review, since six separate
+  passes would settle the same seam question six ways.
+
 ## 0.15.0 - 2026-07-26
 
 **Settings points at the jobs file itself, not the folder holding it.**

docs/DEVELOPMENT.md

@@ -19,6 +19,7 @@ Toolchain, dependency, build, and release information for contributors.
    - [Packaging](#packaging)
 6. [CI](#6-ci)
    - [Cutting a release](#cutting-a-release)
+   - [Releasing through the GitHub push mirror](#releasing-through-the-github-push-mirror)
 
 ## 1. Technology Stack and Tools
 
@@ -275,14 +276,33 @@ and `CHANGELOG.md`, matching the local `package-*` scripts.
 
 ### Cutting a release
 
-Bump `src/app/version.go`, then create and publish a release with a matching `v`
+Before tagging:
-tag on the forge (GitHub Releases / Codeberg releases). You can do that from the
+
-web UI or the CLI, e.g.:
+1. Bump `src/app/version.go`. The tag must match it exactly.
+2. Add the version's [CHANGELOG.md](CHANGELOG.md) section.
+3. Retake the README screenshots (`images/screenshot_jobs.PNG`,
+   `images/screenshot_settings.PNG`) if the GUI changed its appearance. This is
+   easy to forget because nothing fails without it: `README.md` is packaged
+   inside every release archive and is what the forge shows on the project page,
+   so a stale shot advertises an application that no longer exists. Take them
+   from a real build, not from a development run with test data.
+4. Run `scripts/test.bat` (or `go vet ./... && go test -race ./...`) and push
+   `main`, so the tag lands on a commit the forge actually has.
+
+Then create and publish a release with a matching `v` tag on the forge (GitHub
+Releases / Codeberg releases). `origin` is the Gitea repository, and GitHub is a
+push mirror of it, so the tag is pushed to Gitea and reaches GitHub through the
+mirror — never created on GitHub directly (see
+[Releasing through the GitHub push mirror](#releasing-through-the-github-push-mirror)):
 
 ```bash
 git tag v0.11.5
-git push origin v0.11.5   # and to the Codeberg remote
+git push origin v0.11.5   # Gitea; and to the Codeberg remote
-gh release create v0.11.5 --generate-notes   # GitHub; publishes the release
+
+# wait for the mirror, then confirm GitHub actually has the tag
+git ls-remote --tags https://github.com/mixeme/gosentry.git v0.11.5
+
+gh release create v0.11.5 --verify-tag --generate-notes   # GitHub; publishes the release
 ```
 
 Publishing the release triggers the workflow: it strips the leading `v` from
@@ -292,4 +312,40 @@ also allows a manual, upload-free build to smoke-test the pipeline.
 
 Codeberg publishing needs a repository secret named `RELEASE_TOKEN` (a Codeberg
 access token with the `write:repository` scope) under
-**Settings → Actions → Secrets**. GitHub uses the built-in `GITHUB_TOKEN`.
+**Settings → Actions → Secrets**. Without it the build and packaging steps still
+succeed, but the upload step fails on authentication and takes the job down with
+it, leaving a published release with no attached assets. GitHub needs no such
+setup: `softprops/action-gh-release` falls back to the built-in `GITHUB_TOKEN`,
+and the workflow already grants it `contents: write`.
+
+### Releasing through the GitHub push mirror
+
+The GitHub repository `mixeme/gosentry` is not a separate remote you push to; it
+is a push mirror driven by Gitea. Gitea mirrors with pruning, so every ref that
+exists on GitHub but not in Gitea is deleted on the next synchronisation.
+
+This is what breaks the obvious way of cutting a GitHub release. `gh release
+create v1.0.0` creates the tag on GitHub when it is missing — a tag Gitea has
+never heard of. The next mirror run prunes it, GitHub orphans the release whose
+tag disappeared and turns it into a draft, and the release looks deleted on the
+Releases page. The archives go with it. Nothing reports an error: the workflow
+ran, the assets uploaded, and the release evaporated afterwards.
+
+The order that works is therefore:
+
+1. `git push origin <tag>` — the tag enters Gitea, which owns it.
+2. Wait for the mirror, or force it with **Settings → Repository → Mirror
+   Settings → Synchronize Now** in Gitea.
+3. `git ls-remote --tags https://github.com/mixeme/gosentry.git <tag>` — confirm
+   GitHub has it.
+4. `gh release create <tag> --verify-tag …` — `--verify-tag` is the guard, not a
+   nicety: without it `gh` silently creates the doomed tag when the mirror has
+   not caught up yet.
+
+Release notes and assets are GitHub-side metadata; a mirror push cannot touch
+them, so once the release sits on a mirrored tag, later synchronisations leave
+it alone. Two consequences follow. Moving a published tag in Gitea force-pushes
+it on GitHub and leaves the release pointing at a different commit, and deleting
+a published tag in Gitea destroys the GitHub release along with its uploaded
+archives — neither is recoverable from the mirror side. Codeberg is unaffected:
+its releases live in the same forge as its tags.