From 1fdcd207e6ff86cfed63488375dbe70dcc8ca75f Mon Sep 17 00:00:00 2001
From: Michael Johnson <buhnux@gmail.com>
Date: Tue, 10 Nov 2026 06:28:33 -0500
Subject: [PATCH] fix(docs): document the default variant's tag, not the first
 one

The README's image tag fell back to the first variant when no variant was tagged latest, so an image whose default is 15-latest documented :15. Prefer a real latest variant, then the variant marked default, and only then the first. Drop the s6 wording from the mkdocs description now that most images run on base-exec.
---
 dbuild/docs.py                    |  5 +++-
 dbuild/templates/README.mkdocs.j2 |  2 +-
 tests/test_docs.py                | 45 +++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/dbuild/docs.py b/dbuild/docs.py
index 5655f75..4c2a841 100644
--- a/dbuild/docs.py
+++ b/dbuild/docs.py
@@ -767,9 +767,12 @@ def _enrich_metadata(cfg: Config, community_override: str | None = None) -> dict
             }
             for v in cfg.variants
         ],
+        # The tag fjord installs: latest when a variant is tagged latest or
+        # the default carries it, else the default variant, not the first.
         "default_tag": next(
             (a for v in cfg.variants if v.default for a in ["latest"] if a in v.aliases),
-            cfg.variants[0].tag if cfg.variants else "latest",
+            "latest" if any(v.tag == "latest" for v in cfg.variants)
+            else next((v.tag for v in cfg.variants if v.default), cfg.variants[0].tag if cfg.variants else "latest"),
         ),
         "architectures": cfg.architectures,
         "appjail": appjail_meta,
diff --git a/dbuild/templates/README.mkdocs.j2 b/dbuild/templates/README.mkdocs.j2
index 542a4f3..08c1a9c 100644
--- a/dbuild/templates/README.mkdocs.j2
+++ b/dbuild/templates/README.mkdocs.j2
@@ -138,7 +138,7 @@ Save the files above, then run `appjail-director up`.
 {% block frontmatter -%}
 ---
 title: "Run {{ title }} on FreeBSD — Native OCI Container"
-description: "{{ description }} Built natively for FreeBSD with s6 supervision, PUID/PGID support, and CI-tested on every release."
+description: "{{ description }} Built natively for FreeBSD with PUID/PGID support and CI-tested on every release."
 ---
 {% endblock %}
 
diff --git a/tests/test_docs.py b/tests/test_docs.py
index 56ec24e..d3773f9 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -205,6 +205,51 @@ def test_service_image_gets_one_way_per_runtime(self):
                 self.assertNotIn(gone, readme)
 
 
+class TestReadmeDefaultTag(unittest.TestCase):
+    """The README's image tag is the default variant's when no latest is published."""
+
+    def _readme(self, variants: str) -> str:
+        with tempfile.TemporaryDirectory() as d:
+            repo = Path(d)
+            (repo / ".daemonless").mkdir()
+            (repo / "compose.yaml").write_text(COMPOSE_YAML.format(name="testapp").replace("  docs: manual\n", ""))
+            (repo / "Containerfile.j2").write_text(CONTAINERFILE_J2)
+            (repo / ".daemonless" / "config.yaml").write_text("build:\n  variants:\n" + variants)
+            with _chdir(repo):
+                cfg = dbuild_config.load(repo)
+                self.assertEqual(docs.run(cfg, argparse.Namespace(community=None)), 0)
+            return (repo / "README.md").read_text()
+
+    def test_default_variant_without_latest(self):
+        readme = self._readme(
+            "    - tag: \"15\"\n"
+            "    - tag: 15-latest\n"
+            "      default: true\n"
+        )
+        self.assertIn(':15-latest"', readme)
+        self.assertNotIn(':15"', readme)
+
+    def test_latest_alias_on_the_default_wins(self):
+        readme = self._readme(
+            "    - tag: pkg\n"
+            "      default: true\n"
+            "      aliases: [\"latest\"]\n"
+        )
+        self.assertIn(':latest"', readme)
+
+    def test_a_latest_variant_wins_over_the_default(self):
+        readme = self._readme(
+            "    - tag: latest\n"
+            "    - tag: pkg\n"
+            "      default: true\n"
+        )
+        self.assertIn(':latest"', readme)
+
+    def test_no_default_falls_back_to_the_first(self):
+        readme = self._readme("    - tag: \"15\"\n    - tag: \"16\"\n")
+        self.assertIn(':15"', readme)
+
+
 class TestReadmeWithSidecar(unittest.TestCase):
     """An app shipped with its database is documented as its real compose.