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/ci.yml

@@ -3,22 +3,21 @@
 # Push to dev:   typecheck + lint + test + build :dev
 # Push to main:  typecheck + lint + test + build :latest + :<sha>
 #
-# THAT IS THE COMPLETE TAG SET (rule 145). No version-shaped image tag in any lane:
-# nothing pins one — verified by looking for a consumer, not for whether one is
-# imaginable — and the git release tag is a different object in a different system
-# (step 7). The image is addressed by CHANNEL or by COMMIT; the release by date.
+# THAT IS THE COMPLETE TAG SET. No version-shaped image tag in any lane: nothing
+# pins one, and the git release tag is a different object in a different system.
+# The image is addressed by CHANNEL or by COMMIT; the release by date.
 #
 # A `v*` tag builds nothing at all. The merge to main already published everything,
-# so a tag rebuilding that same source would re-push :<sha> with different bytes,
-# which rule 145 forbids even when they match.
+# and a tag rebuilding that same source would re-push :<sha>, which a published tag
+# never allows.
 #
-# main is the production line, so a merge moves :latest to its tip (family rule 46)
-# — no version release required. :<sha> is the immutable rollback unit, and it is
-# on main ONLY: a sha tag per dev push is a rollback target nobody has ever pulled,
-# accumulating forever, for a channel whose entire contract is that it moves.
+# main is the production line, so a merge moves :latest to its tip — no version
+# release required. :<sha> is the immutable rollback unit, and it is on main ONLY: a
+# sha tag per dev push is a rollback target nobody pulls, accumulating forever, for
+# a channel whose entire contract is that it moves.
 #
 # Required secret (repo -> Settings -> Secrets -> Actions):
-#   REGISTRY_TOKEN  -- Forgejo PAT with write:packages scope
+#   REGISTRY_TOKEN  -- forge PAT with write:packages scope
 # The registry username is derived from github.repository_owner (public — it's in
 # the image path), so no REGISTRY_USER secret is needed.
 name: CI & Build
@@ -28,13 +27,12 @@ on:
     # NO `paths:` FILTER, and unlike the client lanes this one does not skip either —
     # the image ALWAYS builds. Two reasons:
     #
-    #   * Rule 145 promises that every push to `main` publishes a `:<sha>`, so any
-    #     production commit is addressable. A path filter quietly broke that promise
-    #     for a docs-only merge: no trigger, no image, no sha tag for that commit.
+    #   * Every push to `main` publishes a `:<sha>`, so any production commit is
+    #     addressable. A path filter would break that for a docs-only merge: no
+    #     trigger, no image, no sha tag for that commit.
     #   * It is the artifact most exposed to base-image staleness (`python:3.12-slim`
     #     is a floating tag and this can face the internet), and building every push
-    #     picks those updates up. That is why note 3127 §4's base tension does not
-    #     bite here — the one artifact it would apply to never skips.
+    #     picks those updates up.
     #
     # Affordable because it is the cheap one: ~15 seconds, against 6 and 9 minutes
     # for the clients, which is why THEY skip and this does not.
@@ -62,17 +60,17 @@ jobs:
   #
   # A push touching the Android app runs BOTH workflows at once. Building here
   # would bake in the PREVIOUS client and then, when the new one landed, there
-  # would be no second build — `:<sha>` is the immutable rollback unit (rule 46)
+  # would be no second build — `:<sha>` is the immutable rollback unit
   # and rebuilding it with different content would make it neither.
   #
   # So on such a push this workflow stands down, and the Android lane dispatches it
   # when it is finished. Exactly one image per commit, containing the client from
   # that commit.
   #
-  # The path list below MUST match android.yml's trigger. Two places holding one
-  # decision is the recurring failure in this repo (issues 2181-2183); it is here
-  # because a workflow cannot read another's filters, and it is a `git diff` rather
-  # than a config so at least it is inspectable in the log.
+  # The path list below MUST match android's file set in packaging/version.sh. Two
+  # places holding one decision drift apart; it is here because this gate needs the
+  # answer before the Android lane has decided, and it is a `git diff` rather than a
+  # config so at least it is inspectable in the log.
   gate:
     name: Build now, or wait for Android?
     if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main'
@@ -125,11 +123,10 @@ jobs:
           echo "Changed in this push:"
           echo "$changed" | sed 's/^/    /'
 
-          # MUST match android's file set in packaging/version.sh. `packaging/` was
-          # missing here after step 4 added it there — so a packaging-only push had
-          # the Android lane rebuild and dispatch while this gate ALSO let the image
-          # build, producing two images for one commit and, on main, a second push of
-          # the same :<sha> with different bytes. Rule 145's exact prohibition.
+          # MUST match android's file set in packaging/version.sh. A path missing here
+          # lets a push touching only it rebuild and dispatch from the Android lane
+          # while this gate ALSO lets the image build: two images for one commit and,
+          # on main, a second push of the same :<sha> with different bytes.
           if echo "$changed" | grep -qE '^(android/|core/|packaging/|Cargo\.toml$|Cargo\.lock$|\.forgejo/workflows/android\.yml$)'; then
             echo ""
             echo "This push also changes the Android client. Standing down: the"
@@ -145,8 +142,8 @@ jobs:
 
   # The web's whole verification: the type check, then its unit tests. Both in the
   # job `build` already needs, so a red web test blocks the image like any other
-  # lane (rule 177). The unit tests arrived with #5166; before them the web copy of
-  # the note grammar, mirrored in Rust and Python, was guarded by nothing.
+  # lane. Among other things they guard the web copy of the note grammar, which is
+  # mirrored in Rust and Python.
   typecheck:
     name: Web typecheck and unit tests
     if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main'
@@ -203,17 +200,16 @@ jobs:
         # and runs in the job below.
         run: /opt/venv/bin/python -m pytest tests/ -q -m "not integration"
 
-  # Real-Postgres lane (family rule 6). Until this existed, `alembic upgrade head` ran
-  # for the first time when the operator's container started — 26 revisions, none of
-  # them ever executed by CI — and the schema the migrations build had never been
-  # checked against the models that read it.
+  # Real-Postgres lane: `alembic upgrade head` runs here before any deployment runs
+  # it, and the schema the migrations build is checked against the models that read
+  # it.
   #
   # Gates the build, along with every other lane — see the `build` job's `needs`.
   #
-  # Job key stays separator-free ("integration") with no `name:` — rule 80. act_runner
+  # Job key stays separator-free ("integration") with no `name:`. act_runner
   # derives the service-container name from the truncated job display name, and the
   # discovery step below filters `docker ps` by it. Service hostnames are not routable
-  # on this runner (rule 79), so the step resolves the container's bridge IP.
+  # on this runner, so the step resolves the container's bridge IP.
   integration:
     if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main'
     runs-on: python-ci
@@ -251,8 +247,8 @@ jobs:
           docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
           # Only THIS job's services. The runner's docker daemon is shared, so another
           # repo's job can be running beside this one, and a job-name filter matches its
-          # containers too (Steward run 8358 and Inkwell run 8653 each took another repo's
-          # Postgres). act names every container of a task GITEA-ACTIONS-TASK-<n>-...: read
+          # containers too, and would take another repo's Postgres. act names every
+          # container of a task GITEA-ACTIONS-TASK-<n>-...: read
           # <n> from our own container (its id is in the /etc/hostname bind mount) and
           # require exactly one match.
           SELF=$(grep -o '/containers/[0-9a-f]\{64\}/' /proc/self/mountinfo | head -n1 | cut -d/ -f3 || true)
@@ -264,7 +260,7 @@ jobs:
           PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
           test -n "$PG_IP"
           export INKWELL_DATABASE_URL="postgresql+asyncpg://inkwell:ci_integration@${PG_IP}:5432/inkwell_test"
-          # Wait for Postgres to accept connections. `run:` is busybox sh (rule 81) —
+          # Wait for Postgres to accept connections. `run:` is busybox sh —
           # no bash /dev/tcp — so use the Python that is always present here.
           /opt/venv/bin/python - "$PG_IP" <<'PY'
           import socket, sys, time
@@ -277,7 +273,7 @@ jobs:
           else:
               sys.exit("postgres did not become reachable")
           PY
-          # Real migrations build the schema, never metadata.create_all (rule 82) —
+          # Real migrations build the schema, never metadata.create_all —
           # testing a schema no deployment has ever seen would prove nothing. This
           # step IS the migration test: a broken revision fails the job here.
           /opt/venv/bin/alembic upgrade head
@@ -285,15 +281,9 @@ jobs:
 
   build:
     name: Build & push image
-    # Every lane gates the build. This once stopped at lint + typecheck, on the
-    # reasoning that DB-backed testing happened manually against the dev image
-    # rather than on every push — true until 6f21db8 added the integration lane,
-    # and false since.
-    #
-    # What that gap cost: run 4293 failed `test` and published :dev and :<sha>
-    # anyway, so the deployed server ran a build whose test lane was red. An image
-    # tag is the rollback substrate (family rule 46); one that can be published
-    # from a failing run is not a substrate you can roll back TO.
+    # Every lane gates the build. An image tag is the rollback substrate, and one
+    # that can be published from a failing run is not a substrate you can roll back
+    # TO.
     needs: [gate, typecheck, lint, test, integration]
     if: needs.gate.outputs.build == 'true'
     runs-on: python-ci
@@ -306,22 +296,20 @@ jobs:
       - uses: actions/checkout@v6
         with:
           # Derives a version — see the note in desktop.yml. Depth-1 sees one commit
-          # and produces a too-low value silently, with the lane green (§6.1).
+          # and produces a too-low value silently, with the lane green.
           fetch-depth: 0
 
       - name: Generate image tags and version
         id: tags
-        # run: steps execute under busybox sh (family rule 81), so use POSIX `case`,
+        # run: steps execute under busybox sh, so use POSIX `case`,
         # NOT bash `[[ ]]`.
         run: |
           # The image's version is DERIVED from its own shipped files — including the
           # Android client it bakes in, which is why an APK-only change re-versions
-          # it. One value and no ordering key: nothing compares a server image, so
-          # §2 says do not invent one just because the other artifacts have one.
+          # it. One value and no ordering key: nothing compares a server image.
           #
-          # This was a short sha on main and the literal "dev" elsewhere, which could
-          # not answer "how old is this instance?" — the question that actually gets
-          # asked of a self-hosted app running in several places.
+          # Date-shaped, because "how old is this instance?" is the question that
+          # actually gets asked of a self-hosted app running in several places.
           BUILD_VERSION="$(sh packaging/version.sh display server)"
           case "${{ github.ref }}" in
             refs/heads/dev)
@@ -345,11 +333,11 @@ jobs:
 
       # Bake EVERY client in, on every image build, so a self-hoster gets a working
       # app for their machine from the server holding their notes — without an
-      # account on this forge, which is private (issue 2091) and is why serving them
-      # from a release page was never an option for anybody but the operator.
+      # account on this forge, which is private, so its release pages serve nobody
+      # but the forge's own users.
       #
       # ~104 MB on top of the ~85 MB image, almost all of it the AppImage. That is
-      # the price of the product being complete (rule 23), and the AppImage is not
+      # the price of the product being complete, and the AppImage is not
       # optional within it: it is the ONLY bundle that can replace itself in place,
       # so a server without one cannot serve in-app updates to anyone.
       #
@@ -367,12 +355,8 @@ jobs:
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: |
           # THE CHANNEL IS A PROPERTY OF THE IMAGE. A :dev image serves dev clients;
-          # :latest serves stable ones. This read `download/dev` unconditionally
-          # until M314 step 3, on every branch — so every stable server shipped a
-          # dev-channel APK to anyone who downloaded the client from it. Not a
-          # versioning gap; a plain defect, and the reason the channel is chosen here
-          # rather than inside the script: the caller is what knows which image it is
-          # building.
+          # :latest serves stable ones. The channel is chosen here rather than inside
+          # the script because the caller is what knows which image it is building.
           case "${{ github.ref_name }}" in
             main) channel=stable ;;
             *)    channel=dev ;;