.gitea/workflows/release.yml

@@ -1,4 +1,5 @@
 name: Release
+# The Hub overview names a released tag, so it is published here only, never on a push to main.
 on:
   push:
     tags: ['v[0-9]+.[0-9]+.[0-9]+']

.gitea/workflows/renovate.yml

@@ -38,6 +38,8 @@ jobs:
       - uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0
+          # A persisted token outranks the PAT in the push URL, and Gitea runs nothing for its pushes.
+          persist-credentials: false
       - name: Tag a release for what Renovate merged
         env:
           RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}

AGENTS.md

@@ -340,10 +340,10 @@ Revisit only if the stated reason stops holding.
   *text* guard — the test image ships neither `git` nor `bash`. This is why the Docker Hub overview is
   `release-tooling/dockerhub-overview.md.tmpl` and not a `.md`: a release reads it and a unit test
   guards it, so giving it a `.md` name would let a broken `{{VERSION}}` merge with its own guard
-  skipped. `README.md` is the one markdown a test reads — `release-tooling/contract-version.test.ts`
-  checks its `apiVersion` samples — and a README-only change skips that check; accepted, because
-  those samples are illustrative and the copies that matter (`examples/`, `views/`, the template) are
-  gated. **Valid while no markdown file is rendered or executed.**
+  skipped. `README.md` is the one markdown tests read, and a README-only change skips them. Accepted:
+  the `apiVersion` samples `release-tooling/contract-version.test.ts` checks are illustrative, and
+  the copies that matter (`examples/`, `views/`, the template) are gated. A Hub page command the
+  README dropped (`release-tooling/dockerhub-overview.test.ts`) fails the next gated change. **Valid while no markdown file is rendered or executed.**
 - **CI docker logins share the runner host's Docker config.** The act_runner is host-mode, so
   `docker login`/`logout` in the workflows mutate one shared `~/.docker/config.json`: concurrent jobs
   can race (one job's logout can 401 another's push — recover by re-running), and tokens sit in that

CHANGELOG.md

@@ -6,6 +6,12 @@ at boot. Entries start at 0.3.0.
 
 ## Unreleased
 
+### Every release reaches Docker Hub, and the Hub page has a short description
+
+Releases 0.4.1 to 0.4.20 were tagged in git but never published to Docker Hub or as semver tags in
+the Gitea registry; they are now, and every later release is. The Hub page gains a one-line
+description.
+
 ### The admin example stops an administrator locking themselves out through a group
 
 On the Groups screen, unticking a permission on a group you are in, removing yourself (or a nested

README.md

@@ -68,6 +68,16 @@ From here, render real pages against the app shell and fetch upstream data — s
 [Building plugins](#building-plugins) and the runnable reference in
 [`examples/plugins/scheduling/`](examples/plugins/scheduling/).
 
+**Without a clone**, the image runs a trial stack on its own. Save the `compose.yml` the
+[Docker Hub page](https://hub.docker.com/r/larvit/plainpages) shows, then extract the Ory config the
+image ships and start, with `X.Y.Z` the release that page names. The page goes on to a first plugin:
+
+```bash
+docker run --rm larvit/plainpages:X.Y.Z tar -cf - ory | tar -xf -
+mkdir -p plugins
+docker compose up -d
+```
+
 ## Contents
 
 - [Goals](#goals)
@@ -1594,7 +1604,7 @@ whose `major.minor` disagrees with `HOST_API_VERSION` and naming the value to se
 **The Docker Hub overview** is published by a separate `publish-overview` job from
 [`release-tooling/dockerhub-overview.md.tmpl`](release-tooling/dockerhub-overview.md.tmpl), with
 `{{VERSION}}` rendered to the release, so the Plainpages tag it tells adopters to pull cannot go
-stale. Its sidecar pins are Renovate-managed and gated against this repo's own compose files, so the
+stale. The same job sets the page's short description. Its sidecar pins are Renovate-managed and gated against this repo's own compose files, so the
 quick start stays a topology CI has actually run.
 It is its own job for two reasons: the images are already pushed and irreversible by then, so a Hub
 outage leaves the promotion green and the images untouched; and the page has its own door — run the

docs/reading-cost.md

@@ -192,3 +192,20 @@ Read most (opens and searches):
 - `ci.sh` 1
 - `examples/plugins/admin/admin-clients.test.ts` 1
 - `examples/plugins/admin/admin-grants.test.ts` 1
+
+## Reading cost, chunk 4a8c9037acde, finished 2026-10-31T10:07:56Z
+
+126616 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `src/http/app-admin.test.ts` 7
+- `examples/plugins/admin/admin-groups.ts` 4
+- `README.md` 3
+- `todo.md` 3
+- `AGENTS.md` 2
+- `examples/plugins/admin/README.md` 2
+- `examples/plugins/admin/admin-grants.ts` 2
+- `examples/plugins/admin/i18n/en-US.ts` 2
+- `CHANGELOG.md` 1
+- `examples/plugins/admin/admin-groups.test.ts` 1

release-tooling/auto-release.test.ts

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+test("auto-release's checkout doesn't persist credentials, so the tag push authenticates as renovate-bot", () => {
+  const workflow = readFileSync(".gitea/workflows/renovate.yml", "utf8");
+  const job = workflow.slice(workflow.indexOf("\n  auto-release:"));
+  const checkout = job.slice(job.indexOf("actions/checkout@"), job.indexOf("\n      - name:"));
+  assert.match(checkout, /^\s+persist-credentials: false$/m);
+});

release-tooling/dockerhub-overview.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { test } from "node:test";
-import { jwtFrom, leftoverPlaceholders, renderOverview } from "./dockerhub-overview.ts";
+import { DESCRIPTION, hubPatch, jwtFrom, leftoverPlaceholders, renderOverview } from "./dockerhub-overview.ts";
 
 const TEMPLATE = "release-tooling/dockerhub-overview.md.tmpl";
 const template = () => readFileSync(TEMPLATE, "utf8");
@@ -46,3 +46,28 @@ test("jwtFrom accepts only a non-empty string token, never throwing on a hostile
   assert.equal(jwtFrom({ token: "" }), null);
   assert.equal(jwtFrom({ token: 42 }), null);
 });
+
+test("the short description opens a README sentence and fits Docker Hub's 100 characters", () => {
+  const readme = readFileSync("README.md", "utf8").replaceAll("**", "");
+  assert.ok(DESCRIPTION.trim() !== "" && DESCRIPTION.length <= 100, `${DESCRIPTION.length} characters`);
+  const escaped = DESCRIPTION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  assert.match(readme, new RegExp(`(?:\\n\\n|\\.\\s)${escaped}(?=[\\s.:,])`));
+});
+
+test("every command the overview shows, the README shows too", () => {
+  const commands = (source: string) =>
+    [...source.matchAll(/```bash\n(.*?)```/gs)].flatMap((block) =>
+      (block[1] ?? "")
+        .split("\n")
+        .map((line) => (line.split(" #")[0] ?? "").trim().replace(/larvit\/plainpages:\S+/g, "larvit/plainpages:X.Y.Z"))
+        .filter((line) => line !== ""),
+    );
+  const shown = new Set(commands(readFileSync("README.md", "utf8")));
+  const published = commands(template());
+  assert.ok(published.length > 0, `${TEMPLATE} should show commands`);
+  for (const command of published) assert.ok(shown.has(command), `${TEMPLATE} shows ${command}, which README.md doesn't`);
+});
+
+test("the PATCH carries the short description beside the overview", () => {
+  assert.deepEqual(hubPatch("# page"), { description: DESCRIPTION, full_description: "# page" });
+});

release-tooling/dockerhub-overview.ts

@@ -1,6 +1,3 @@
-// Publishes the Docker Hub repository overview from dockerhub-overview.md.tmpl, rendering
-// `{{VERSION}}` to the release being published.
-
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -8,6 +5,12 @@ const HUB = "https://hub.docker.com/v2";
 const TIMEOUT_MS = 30_000;
 const VERSION = /^\d+\.\d+\.\d+$/;
 
+export const DESCRIPTION = "A self-hostable foundation for server-rendered web applications";
+
+export function hubPatch(overview: string): { description: string; full_description: string } {
+  return { description: DESCRIPTION, full_description: overview };
+}
+
 export function renderOverview(source: string, version: string): string {
   return source.replaceAll("{{VERSION}}", version);
 }
@@ -81,21 +84,21 @@ async function main(): Promise<number> {
   if (!jwt) return fail("Docker Hub login returned no token");
 
   const res = await post(`${HUB}/repositories/${repo}/`, {
-    body: JSON.stringify({ full_description: body }),
+    body: JSON.stringify(hubPatch(body)),
     headers: { authorization: `Bearer ${jwt}`, "content-type": "application/json" },
     method: "PATCH",
   });
   if ("error" in res) return fail(`Docker Hub unreachable: ${res.error}`);
   if (!res.ok) {
     return fail(
-      `Docker Hub overview PATCH failed: ${res.status} ${res.text}` +
+      `Docker Hub description and overview PATCH failed: ${res.status} ${res.text}` +
         (res.status === 403
           ? "\n403 means DOCKERHUB_TOKEN lacks the delete scope — editing the overview needs " +
             "read/write/delete, which pushing images alone does not (README -> CI/CD)."
           : ""),
     );
   }
-  process.stdout.write(`Docker Hub overview updated for ${repo} at ${version}\n`);
+  process.stdout.write(`Docker Hub description and overview updated for ${repo} at ${version}\n`);
   return 0;
 }
 

todo.md

@@ -12,7 +12,6 @@
 
 | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
 |---|---|---|---|---|---|---|---|---|---|---|---|
-| 1 | 0.4.21 |  | owner | **Publish every release to Docker Hub, and give the Hub page its short description.** | 3 | 3 | 2 | 6 | 5 | 1 by 3 | 1.3 |
 | 32 | 0.4.21 |  |  | **Fail the gate on a stylesheet feature the browser floor lacks, unless it is guarded.** | 4 | 2 | 2 | 6 | 7 | code health by 2 | 1.1 |
 | 13 | 0.4.21 |  |  | **Accept a verification code pasted with surrounding whitespace.** | 4 | 2 | 3 | 7 | 7 | 2 by 8 | 1.0 |
 | 19 | 0.5.0 |  | question | **Run the documented Docker commands on macOS and fix whatever misbehaves.** | 2 | 2 | 1 | 3 | 3 | 1 by 3 | 3.3 |
@@ -28,17 +27,6 @@
 
 ## Details
 
-### 1. Publish every release to Docker Hub, and give the Hub page its short description.
-
-Hub's newest tag is 0.4.0, while git has v0.4.1 onwards, and the overview still says 0.4.0. No
-`release.yml` run exists for the tags auto-release pushes as `renovate-bot`; find out why Gitea
-doesn't fire `push: tags` for them, fix it, and backfill the missing tags. fejkdata did this
-(`../fejkdata`, commits `51d924a` and `34c8234`), and two parts port directly: a one-line
-description riding the existing PATCH as its `description` field, and a unit test that the
-description opens a README sentence and every command the overview shows appears in the README.
-fejkdata also syncs the page on any push to `main`, with its own token in an environment only `main`
-may use; decide whether that fits here, where `{{VERSION}}` must render a released tag.
-
 ### 32. Fail the gate on a stylesheet feature the browser floor lacks, unless it is guarded.
 
 Nothing checks README → "Two browser floors", and no E2E engine is old enough to show a break.