Root, CI, docs and packaging describe the project to a stranger (#6225)

#6225 "Comment standard sweep: root, config, CI workflows, docs and
packaging", milestone 546 "Bring the repo to the comment standard (rule 32)
and compose defaults (rule 198)".

- README restructured in newcomer order: what it is, quick start,
  configuration, setup pitfalls, updating and backups, features,
  troubleshooting, development, licence. Its quick-start compose carries
  no restart policy.
- Dockerfile and .env.example trimmed to one or two lines per setting.
- Workflows, packaging scripts and docs lose issue, run, note, rule and
  milestone references and their history narration. Comments that still
  described path filters and "step 6" as future work now state what the
  workflows do.
- ci-requirements.md rewritten against the current workflows. It said the
  build gated on typecheck and lint only, the integration lane did not
  gate, a v* tag published :latest, and ci-tauri lacked bsdtar and zstd;
  none of those is true now (the last checked against run 9630's log).
- Echo strings in guard-forward.sh and version.sh drop their note
  citations; every string a test asserts on is unchanged.

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

packaging/guard-forward.sh

@@ -6,18 +6,17 @@
 #   guard-forward.sh compare   <a> <b>              exit 0 iff a sorts below b
 #   guard-forward.sh published <artifact> <channel> print what the channel serves
 #
-# Note 3127 §6.3. Everything else in this milestone derives a number and trusts it;
-# this is the one thing that checks the answer against reality before a user gets it.
+# Everything else in the versioning derives a number and trusts it; this is the one
+# thing that checks the answer against reality before a user gets it.
 #
 # WHAT IT CATCHES that nothing else does:
 #
-#   * A SQUASH OR REBASE MERGE (§6.2). Both rewrite the committer date, so `main`
-#     could stamp a value unrelated to the dev commit it merged. Rule 153 mandates
-#     plain merge commits — but that rule governs people, and a forge UI's squash
-#     button does not read it.
+#   * A SQUASH OR REBASE MERGE. Both rewrite the committer date, so `main` could
+#     stamp a value unrelated to the dev commit it merged. This repo merges with
+#     plain merge commits, but a forge UI's squash button is still one click away.
 #   * A REBUILD OF AN OLDER COMMIT. Commit time can go backwards; this is the entire
-#     mitigation for the desktop key's clock choice (step 4), and the thing to
-#     revisit first if this repo ever starts rebuilding old commits routinely.
+#     mitigation for the desktop key's clock choice, and the thing to revisit first
+#     if this repo ever starts rebuilding old commits routinely.
 #   * CLOCK SKEW between runners, for a build-time key.
 #
 # What it does NOT catch, because something better does: a shallow clone. That is
@@ -26,8 +25,8 @@
 #
 # TOO-LOW IS THE UNRECOVERABLE DIRECTION. A version below what is published means
 # every installed client reports "up to date" forever and there is no build you can
-# ship to fix it — you have to get back ABOVE the bad number. That is #2183 and
-# #2993's shared symptom, and it is why this fails the lane rather than warning.
+# ship to fix it — you have to get back ABOVE the bad number. That is why this fails
+# the lane rather than warning.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
@@ -54,8 +53,8 @@ version_lt() {
   return 1   # equal
 }
 
-# Auth if we have it, anonymous if not — the releases are public, but a token costs
-# nothing and keeps this working if that ever changes.
+# Auth if we have it, anonymous if not — a token costs nothing, and a private repo's
+# releases need one.
 #
 # MISSING CURL IS FATAL, not empty. Every fetch here ends in `|| true` so a network
 # blip reads as "nothing published yet" and passes — which is right for a genuinely
@@ -78,7 +77,7 @@ fetch() {
 
 # What the channel is serving, per artifact. ONE definition of where to look, shared
 # with `should-build.sh` — the skip decision and the guard must agree about what is
-# published, and two readers of one fact is how this repo keeps producing #2181-2183.
+# published, and two readers of one fact drift apart.
 #
 # EVERY LOOKUP HERE MUST SUCCEED EVEN WHEN IT FINDS NOTHING. That is what the `|| true`
 # on each pipeline is for, and it is load-bearing rather than defensive noise.
@@ -89,15 +88,14 @@ fetch() {
 # exits non-zero kills the script before that branch is ever reached. Silently, too:
 # everything the pipeline would have said went into the capture rather than the log.
 #
-# WHICH COMMAND THE PIPELINE HAPPENS TO END ON decides whether that fires, which is the
-# part worth remembering. `sed` on empty input exits 0; `grep` exits 1. Three of these
-# four lookups end in `sed` and were fine. The one that ends in `grep -oE '[0-9]+$'` —
-# Android's version_code — was not, and it failed the whole Android lane on the first
-# merge to `main` (run 4857): exit 1, no output, 0.16 seconds, on the one channel that
-# had no APK published yet. Its three neighbours hid it until then.
+# WHICH COMMAND THE PIPELINE ENDS ON decides whether that fires, which is the part
+# worth remembering. `sed` on empty input exits 0; `grep` exits 1. Three of these four
+# lookups end in `sed`; the one that ends in `grep -oE '[0-9]+$'` — Android's
+# version_code — would fail the lane, silently, on any channel with no APK published
+# yet.
 published_for() {
   # The channel's release TAG, not its name — `dev` lives on `dev-rolling`
-  # (packaging/channel-tag.sh, Scribe #2184). `|| exit 2` rather than letting an
+  # (packaging/channel-tag.sh). `|| exit 2` rather than letting an
   # empty tag through: a lookup against `.../download//latest.json` would find
   # nothing and read as "nothing published", which this guard PASSES.
   _tag="$(sh "$ROOT/packaging/channel-tag.sh" "$2")" || exit 2
@@ -173,7 +171,7 @@ case "$artifact" in
     published="$(published_for desktop "$channel")"
     # COMMIT time, so EQUALITY IS THE ORDINARY CASE: an unchanged source derives
     # exactly what it derived last time, and `<=` would fail every no-change build.
-    # §6.3 says *strictly* less for exactly this reason.
+    # So this fails only on *strictly* less.
     strict=""
     ;;
   android)
@@ -212,7 +210,7 @@ if version_lt "$derived" "$published"; then
   echo "  forever, and no later build fixes that until one climbs back above the" >&2
   echo "  bad number. Do not force past this." >&2
   echo "" >&2
-  echo "  Usual causes (note 3127 §6.2, §6.3):" >&2
+  echo "  Usual causes:" >&2
   echo "    - a squash or rebase merge rewrote the committer date" >&2
   echo "    - this build is a rebuild of an older commit" >&2
   echo "    - clock skew between runners (build-time keys)" >&2