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>

.forgejo/workflows/desktop.yml

@@ -4,22 +4,20 @@
 # It DOES run on frontend changes. tauri's generate_context! embeds the built
 # frontend in the binary, so a frontend commit that never triggers this ships to
 # the web and silently never reaches the desktop app — and desktop, web and Android
-# are peer surfaces held to one quality bar, not a primary and its fallbacks. The
-# filter was once narrowed to the adapter/bridge directories against a "~20-40 min"
-# build; measured runs are 4-5 minutes, so the cost that justified the narrowing
-# isn't there.
+# are peer surfaces held to one quality bar, not a primary and its fallbacks. A
+# build takes 4-5 minutes, so there is no cost worth narrowing that for.
 #
 # Toolchain comes from the ci-tauri image (Rust + Node + WebKitGTK 4.1 + tauri-cli);
-# runs-on is just a registered scheduling label (Label Model B), not a per-purpose
+# runs-on is just a registered scheduling label, not a per-purpose
 # runner. The frontend is built here because tauri's generate_context! embeds it.
 name: Desktop (Tauri)
 
 on:
   push:
-    # NO `paths:` FILTER. It was a second, independent statement of this artifact's
-    # file set, hand-kept beside the one in `packaging/version.sh`, and it drifted
-    # from it within a day (85ead4d). The `decide` job below reads the real set and
-    # skips in seconds when nothing moved — one definition, one reader (§3).
+    # NO `paths:` FILTER. It would be a second, hand-kept statement of this artifact's
+    # file set beside the one in `packaging/version.sh`, and the two drift. The
+    # `decide` job below reads the real set and skips in seconds when nothing moved —
+    # one definition, one reader.
     #
     # The cost is that this workflow starts on every push rather than on a matching
     # one. That is a ~15s container for a decision, against a lane that cannot
@@ -40,13 +38,9 @@ permissions:
 jobs:
   # Does anything need building at all?
   #
-  # ONE reader of ONE definition — the file sets in `packaging/version.sh` — replacing
-  # the `paths:` filters that used to state the same fact a second time. They drifted
-  # from it within a day: `packaging/` was added to the sets and not to the filters,
-  # so the commit fixing a derivation bug never ran on the two lanes it fixed
-  # (85ead4d). Note 3127 §3 warns about exactly that duplication.
+  # ONE reader of ONE definition: the file sets in `packaging/version.sh`.
   #
-  # THE GUARD RUNS HERE, so it runs on every path INCLUDING the skip one (§6.3).
+  # THE GUARD RUNS HERE, so it runs on every path INCLUDING the skip one.
   # Skipping because "the channel already serves this version" is indistinguishable
   # from "we derived a stale value that happens to match" unless something checks.
   decide:
@@ -60,7 +54,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          # Derives a version — depth-1 is silently wrong (§6.1).
+          # Derives a version — depth-1 is silently wrong.
           fetch-depth: 0
 
       - name: Decide
@@ -76,13 +70,12 @@ jobs:
           echo "build=$(sh packaging/should-build.sh desktop "$channel")" >> $GITHUB_OUTPUT
 
   # The workspace checks, in their OWN job, so that BOTH publishing jobs can need
-  # them (rule 177: nothing publishes on red).
+  # them: nothing publishes on red.
   #
-  # They used to be steps inside `build`, which gated the Linux publish and nothing
-  # else. `windows` needed only `decide`, so on run 8411 clippy failed, the Linux job
-  # stopped, and the Windows installer built and published to the dev release in the
-  # same minute (#5184). An edge from each publisher to this job is the gate; a
-  # verdict inside a sibling job is only a report.
+  # As steps inside `build` they would gate the Linux publish and nothing else, and
+  # the Windows installer would publish beside a failed clippy. An edge from each
+  # publisher to this job is the gate; a verdict inside a sibling job is only a
+  # report.
   #
   # Both publishers need it directly rather than through each other, so a Windows
   # failure still never blocks the Linux bundles, and neither waits on the other's
@@ -108,25 +101,20 @@ jobs:
 
       # The web's unit tests, HERE as well as in ci.yml. The installers embed this
       # frontend, and ci.yml's verdict is invisible to this workflow — run there only,
-      # a red web test would still let both installers publish (rule 177).
+      # a red web test would still let both installers publish.
       - name: Web unit tests
         run: npm test
         working-directory: frontend
 
       # --locked on the FIRST cargo invocation is the lockfile gate: it fails the
       # run if Cargo.toml and the committed Cargo.lock disagree, instead of silently
-      # re-resolving (issue 2102). Both publishing jobs need this job, so neither
+      # re-resolving. Both publishing jobs need this job, so neither
       # bundles a commit whose lockfile drifted.
       #
-      # Run from the REPO ROOT with --workspace, not from desktop/src-tauri.
-      #
-      # These three steps used to run inside the desktop crate, which was right when
-      # it was the only Rust in the repo. After the core was extracted (M12 step 1)
-      # it silently stopped being right: cargo scoped to the desktop PACKAGE, so the
-      # core's 89 tests stopped running and nothing lints the Android uniffi shim at
-      # all. Both crates are dependencies of the desktop, so they still COMPILED —
-      # which is exactly why the gap was invisible, and why a green run kept meaning
-      # less than it looked like it meant.
+      # Run from the REPO ROOT with --workspace, not from desktop/src-tauri. Inside the
+      # desktop crate, cargo scopes to the desktop PACKAGE: the core's tests would not
+      # run and nothing would lint the Android uniffi shim, while both still COMPILE
+      # as dependencies — so the run stays green and the gap stays invisible.
       - name: Clippy
         run: cargo clippy --locked --workspace --all-targets -- -D warnings
 
@@ -148,8 +136,8 @@ jobs:
     name: Tauri desktop (Linux)
     needs: [decide, verify]
     # A deadline, not a budget: warm builds take ~4 minutes. Without one a hung step
-    # runs to the runner's own 30-minute cap, as run 8830 did on a rust-lld link whose
-    # threads had all deadlocked (#5409). Kept under that cap so this one is the limit
+    # runs to the runner's own 30-minute cap, as a rust-lld link whose threads have
+    # all deadlocked will. Kept under that cap so this one is the limit
     # that fires, whatever the runner is configured with.
     timeout-minutes: 20
     if: needs.decide.outputs.build == 'true'
@@ -166,7 +154,7 @@ jobs:
         with:
           # DERIVES A VERSION -> needs the whole history. A depth-1 clone sees one
           # commit and `git log -- <paths>` produces a too-LOW value, silently, with
-          # the lane green — note 3127 §6.1, and the direction you cannot recover
+          # the lane green — the direction you cannot recover
           # from. `packaging/version.sh` fails loudly on an empty result rather than
           # emitting something plausible, which is what turns this into a red lane
           # if it is ever dropped.
@@ -180,10 +168,10 @@ jobs:
 
       # Frontend already built above; skip the beforeBuildCommand rebuild.
       #
-      # createUpdaterArtifacts is applied only when a signing key exists (M10.9):
-      # tauri FAILS the build if it's asked to produce updater artifacts with no key,
-      # so making it conditional is what lets the pipeline stay green before the
-      # operator has added the secret. With the key present, each bundle gets a
+      # createUpdaterArtifacts is applied only when a signing key exists: tauri
+      # FAILS the build if it's asked to produce updater artifacts with no key, so
+      # making it conditional is what lets the pipeline stay green without the
+      # secret. With the key present, each bundle gets a
       # `.sig` beside it — the file the updater actually verifies against.
       - name: Tauri build (deb + AppImage)
         env:
@@ -200,10 +188,10 @@ jobs:
           # The ORDERING KEY, not the display version: this string is what Tauri's
           # updater parses as semver, and what it stamps into bundle FILENAMES that
           # `write-manifest.sh` then selects on. The human-readable version is a
-          # separate value and arrives with the UI that shows it (#3181).
+          # separate value, exported just below.
           version="$(sh ../../packaging/version.sh key desktop)"
           echo "Building desktop ordering key $version"
-          # The DISPLAY version, baked into the binary by `option_env!` (#3181).
+          # The DISPLAY version, baked into the binary by `option_env!`.
           # A different value for a different audience: this is the one a person
           # quotes in a bug report, the key above is the one only a comparator
           # sees. Exported rather than passed as a flag because the macro that
@@ -219,7 +207,7 @@ jobs:
 
       # Tauri's AppImage bundles the build host's graphics/display libs
       # (libEGL/libGL/libdrm/libgbm/libwayland-*), which clash with end-user GPU
-      # drivers and abort to a black window (EGL_BAD_PARAMETER, issue 2021).
+      # drivers and abort to a black window (EGL_BAD_PARAMETER).
       # Strip that host-coupled stack so the app uses the running system's
       # graphics libs; webkit/gtk stay bundled. Runs from the repo root (the
       # script resolves its own paths), overwriting the AppImage in place.
@@ -253,9 +241,9 @@ jobs:
       # control file and cross-checks it against what the ELF actually needs
       # (dpkg-shlibdeps).
       #
-      # We deliberately do NOT set bundle.linux.deb.depends: run 2872 showed
-      # tauri already infers exactly libwebkit2gtk-4.1-0 + libgtk-3-0, so
-      # declaring them again only produced a control file listing each twice.
+      # We deliberately do NOT set bundle.linux.deb.depends: tauri already infers
+      # exactly libwebkit2gtk-4.1-0 + libgtk-3-0, so declaring them again only
+      # produces a control file listing each twice.
       # This step is the guard instead — if tauri's inference ever stops
       # covering what the binary links, the build fails here.
       - name: Verify the .deb
@@ -271,13 +259,12 @@ jobs:
         run: bash desktop/packaging/arch/package-prebuilt.sh
 
       # Make the built .deb + .AppImage downloadable from the run (for hand-testing).
-      # Stock action: it works on this forge since the runner moved to
-      # gitea/runner 3.x, which edits upload-artifact's client-side GHES refusal
-      # out of the action bundle (Scribe snippet #2271). Never @v3 — it uploads
-      # something Gitea stores but will never serve back (it returns artifacts only
-      # through the v4 API, which filters on content_encoding='application/zip').
-      # No continue-on-error: a swallowed upload failure is exactly how 110
-      # unreachable artifacts accumulated here unnoticed. Fail loudly instead.
+      # Stock action: it works on this forge because gitea/runner 3.x edits
+      # upload-artifact's client-side GHES refusal out of the action bundle. Never
+      # @v3 — it uploads something Gitea stores but will never serve back (it returns
+      # artifacts only through the v4 API, which filters on
+      # content_encoding='application/zip'). No continue-on-error: a swallowed upload
+      # failure lets unreachable artifacts pile up unnoticed. Fail loudly instead.
       - name: Upload bundles
         uses: actions/upload-artifact@v7
         with:
@@ -292,14 +279,11 @@ jobs:
 
       # The rolling channel for this branch: `dev` from dev, `stable` from main. Both
       # are releases whose tag never moves, so the updater has a permanent URL to
-      # read — Forgejo has no /releases/latest/download/<asset> route, so "newest"
+      # read — the forge has no /releases/latest/download/<asset> route, so "newest"
       # cannot be named in a URL.
       #
-      # MAIN PUBLISHING HERE is what makes a `v*` tag optional (note 3127 §0). Until
-      # M314 step 3 this job built on main and published nothing, so the stable
-      # channel moved only when somebody cut a tag — that section's diagnostic
-      # failing outright: main publishing was not sufficient for a user to receive
-      # the build.
+      # MAIN PUBLISHING HERE is what makes a `v*` tag optional: a merge to main
+      # reaches stable users with no tag cut.
       #
       # Gated on the signing key INSIDE the script rather than with an `if:`, because
       # the secrets context isn't reliably available to step conditions. Publishing
@@ -315,7 +299,7 @@ jobs:
             echo "No TAURI_SIGNING_PRIVATE_KEY — skipping the channel publish."
             exit 0
           fi
-          # POSIX `case`, not bash `[[ ]]` — these run under busybox sh (rule 81).
+          # POSIX `case`, not bash `[[ ]]` — these run under busybox sh.
           # `prerelease` is true for dev so it does not read as a supported build,
           # and false for stable, which is the real thing.
           case "$GITHUB_REF_NAME" in
@@ -323,7 +307,7 @@ jobs:
             *)    channel=dev;    RELEASE_PRERELEASE=true  ;;
           esac
           # The channel's release TAG, not its name: `dev` publishes on `dev-rolling`
-          # (packaging/channel-tag.sh). A tag named `dev` shadowed the branch.
+          # (packaging/channel-tag.sh). A tag named `dev` would shadow the branch.
           RELEASE_TAG="$(sh packaging/channel-tag.sh "$channel")"
           export RELEASE_TAG RELEASE_PRERELEASE
           echo "Publishing to the $RELEASE_TAG channel."
@@ -355,7 +339,7 @@ jobs:
         with:
           # DERIVES A VERSION -> needs the whole history. A depth-1 clone sees one
           # commit and `git log -- <paths>` produces a too-LOW value, silently, with
-          # the lane green — note 3127 §6.1, and the direction you cannot recover
+          # the lane green — the direction you cannot recover
           # from. `packaging/version.sh` fails loudly on an empty result rather than
           # emitting something plausible, which is what turns this into a red lane
           # if it is ever dropped.
@@ -396,10 +380,10 @@ jobs:
           # The ORDERING KEY, not the display version: this string is what Tauri's
           # updater parses as semver, and what it stamps into bundle FILENAMES that
           # `write-manifest.sh` then selects on. The human-readable version is a
-          # separate value and arrives with the UI that shows it (#3181).
+          # separate value, exported just below.
           version="$(sh ../../packaging/version.sh key desktop)"
           echo "Building desktop ordering key $version"
-          # The DISPLAY version, baked into the binary by `option_env!` (#3181).
+          # The DISPLAY version, baked into the binary by `option_env!`.
           # A different value for a different audience: this is the one a person
           # quotes in a bug report, the key above is the one only a comparator
           # sees. Exported rather than passed as a flag because the macro that
@@ -430,14 +414,11 @@ jobs:
 
       # The rolling channel for this branch: `dev` from dev, `stable` from main. Both
       # are releases whose tag never moves, so the updater has a permanent URL to
-      # read — Forgejo has no /releases/latest/download/<asset> route, so "newest"
+      # read — the forge has no /releases/latest/download/<asset> route, so "newest"
       # cannot be named in a URL.
       #
-      # MAIN PUBLISHING HERE is what makes a `v*` tag optional (note 3127 §0). Until
-      # M314 step 3 this job built on main and published nothing, so the stable
-      # channel moved only when somebody cut a tag — that section's diagnostic
-      # failing outright: main publishing was not sufficient for a user to receive
-      # the build.
+      # MAIN PUBLISHING HERE is what makes a `v*` tag optional: a merge to main
+      # reaches stable users with no tag cut.
       #
       # Gated on the signing key INSIDE the script rather than with an `if:`, because
       # the secrets context isn't reliably available to step conditions. Publishing
@@ -453,7 +434,7 @@ jobs:
             echo "No TAURI_SIGNING_PRIVATE_KEY — skipping the channel publish."
             exit 0
           fi
-          # POSIX `case`, not bash `[[ ]]` — these run under busybox sh (rule 81).
+          # POSIX `case`, not bash `[[ ]]` — these run under busybox sh.
           # `prerelease` is true for dev so it does not read as a supported build,
           # and false for stable, which is the real thing.
           case "$GITHUB_REF_NAME" in
@@ -461,7 +442,7 @@ jobs:
             *)    channel=dev;    RELEASE_PRERELEASE=true  ;;
           esac
           # The channel's release TAG, not its name: `dev` publishes on `dev-rolling`
-          # (packaging/channel-tag.sh). A tag named `dev` shadowed the branch.
+          # (packaging/channel-tag.sh). A tag named `dev` would shadow the branch.
           RELEASE_TAG="$(sh packaging/channel-tag.sh "$channel")"
           export RELEASE_TAG RELEASE_PRERELEASE
           echo "Publishing to the $RELEASE_TAG channel."
@@ -488,7 +469,7 @@ jobs:
         with:
           # DERIVES A VERSION -> needs the whole history. A depth-1 clone sees one
           # commit and `git log -- <paths>` produces a too-LOW value, silently, with
-          # the lane green — note 3127 §6.1, and the direction you cannot recover
+          # the lane green — the direction you cannot recover
           # from. `packaging/version.sh` fails loudly on an empty result rather than
           # emitting something plausible, which is what turns this into a red lane
           # if it is ever dropped.
@@ -519,7 +500,7 @@ jobs:
           # holds the bundles, and the previous build's bundles are dropped once it
           # points at this one. Nothing can reach them, and they are ~100 MB a push.
           #
-          # No tag arm any more. A `v*` tag does not reach this workflow at all — it
+          # No tag arm: a `v*` tag does not reach this workflow at all — it
           # triggers release.yml, which writes a changelog and builds nothing.
           case "${GITHUB_REF_NAME}" in
             main) RELEASE_TAG="$(sh packaging/channel-tag.sh stable)"