repomatic 7.4.0__tar.gz → 7.4.1__tar.gz

{repomatic-7.4.0 → repomatic-7.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repomatic
-Version: 7.4.0
+Version: 7.4.1
 Summary: 🏭 Automate repository maintenance, releases, and CI/CD workflows
 Keywords: changelog-formatter,dependabot-alternative,github-actions,github-labels,github-workflow,gitignore,mailmap,mypy,nuitka,python-automation,release-automation,repository-automation,repository-management,reusable-workflows,software-factory,sphinx-doc,typo,uv,workflow-reusable
 Author: Kevin Deldycke
@@ -59,7 +59,7 @@ Requires-Dist: wcmatch>=10
 Requires-Python: >=3.10
 Project-URL: Changelog, https://github.com/kdeldycke/repomatic/blob/main/changelog.md
 Project-URL: Documentation, https://kdeldycke.github.io/repomatic
-Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.4.0
+Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.4.1
 Project-URL: Funding, https://github.com/sponsors/kdeldycke
 Project-URL: Homepage, https://github.com/kdeldycke/repomatic
 Project-URL: Issues, https://github.com/kdeldycke/repomatic/issues

{repomatic-7.4.0 → repomatic-7.4.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
 build-backend = "uv_build"
-requires = ["uv-build>=0.12"]
+requires = ["uv-build>=0.8"]
 
 [project]
 name = "repomatic"
-version = "7.4.0"
+version = "7.4.1"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -92,7 +92,7 @@ email = "kevin@deldycke.com"
 [project.urls]
 Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 Documentation = "https://kdeldycke.github.io/repomatic"
-Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.4.0"
+Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.4.1"
 Funding = "https://github.com/sponsors/kdeldycke"
 Homepage = "https://github.com/kdeldycke/repomatic"
 Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -119,6 +119,7 @@ docs = [
     "sphinx-copybutton>=0.5.2",
     "sphinx-datatables>=1",
     "sphinx-design>=0.6",
+    "sphinxcontrib-jquery>=4",
     "sphinxcontrib-mermaid>=1.2.3",
     "sphinxext-opengraph>=0.13",
 ]
@@ -130,7 +131,7 @@ typing = [
 ]
 
 [tool.uv]
-required-version = ">=0.12"
+required-version = ">=0.11.15"
 exclude-newer = "1 week"
 
 [tool.uv.dependency-groups.docs]
@@ -147,14 +148,14 @@ module-root = ""
 [tool.nuitka]
 copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed under GPL-2.0-or-later license."
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
-file-version = "7.4.0"
+file-version = "7.4.1"
 include-data-dir = ["repomatic/data/awesome_template=repomatic/data/awesome_template"]
 include-data-files = ["repomatic/templates/*.md=repomatic/templates/"]
 include-package-data = ["click_extra"]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.4.0"
+product-version = "7.4.1"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -244,7 +245,7 @@ source = ["repomatic"]
 precision = 2
 
 [tool.bumpversion]
-current_version = "7.4.0"
+current_version = "7.4.1"
 parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.dev(?P<dev>\d+))?'
 serialize = [
     "{major}.{minor}.{patch}.dev{dev}",

{repomatic-7.4.0 → repomatic-7.4.1}/pyproject.toml.orig

@@ -7,12 +7,12 @@ build-backend = "uv_build"
 # repomatic runs across the ecosystem, where uv versions drift between projects,
 # and a hard ceiling risks a chicken-and-egg deadlock when one project's uv
 # moves ahead of repomatic's next release.
-requires = [ "uv-build>=0.12" ]
+requires = [ "uv-build>=0.8" ]
 
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "repomatic"
-version = "7.4.0"
+version = "7.4.1"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -145,7 +145,7 @@ dependencies = [
 ]
 urls.Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 urls.Documentation = "https://kdeldycke.github.io/repomatic"
-urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.4.0"
+urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.4.1"
 urls.Funding = "https://github.com/sponsors/kdeldycke"
 urls.Homepage = "https://github.com/kdeldycke/repomatic"
 urls.Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -190,6 +190,10 @@ docs = [
   "sphinx-datatables>=1",
   # sphinx-design 0.6 introduced the current directive syntax for cards, grids, and tabs.
   "sphinx-design>=0.6",
+  # sphinxcontrib-jquery is loaded explicitly in docs/conf.py (sphinx-datatables
+  # activates it too late to register jquery.js on its own); declare it so the
+  # build never relies on it arriving only transitively via sphinx-datatables.
+  "sphinxcontrib-jquery>=4",
   # sphinxcontrib-mermaid 1.2.3 fixed mermaid_d3_zoom configuration support.
   "sphinxcontrib-mermaid>=1.2.3",
   # sphinxext-opengraph 0.13 stabilized OpenGraph metadata generation for Sphinx 8+.
@@ -216,7 +220,7 @@ typing = [
 # self-updates). uv.lock stays stable across minors because sync-uv-lock
 # discards a re-lock that only re-spells equivalent markers (see
 # repomatic.uv.sync_uv_lock).
-required-version = ">=0.12"
+required-version = ">=0.11.15"
 # Docs group requires Python >= 3.14 for recent MyST-Parser and click-extra features.
 dependency-groups.docs = { requires-python = ">= 3.14" }
 # Cooldown period: 7-day buffer before using newly released packages.
@@ -243,7 +247,7 @@ copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed u
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 # Numeric only: Nuitka rejects PEP 440 .devN suffixes. Kept in sync with the
 # package version by the dedicated [tool.bumpversion] rule that strips the suffix.
-file-version = "7.4.0"
+file-version = "7.4.1"
 include-data-dir = [
   "repomatic/data/awesome_template=repomatic/data/awesome_template",
 ]
@@ -261,7 +265,7 @@ include-package-data = [ "click_extra" ]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.4.0"
+product-version = "7.4.1"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -383,7 +387,7 @@ run.source = [ "repomatic" ]
 report.precision = 2
 
 [tool.bumpversion]
-current_version = "7.4.0"
+current_version = "7.4.1"
 # Parse versions with an optional .devN suffix (PEP 440).
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
 serialize = [

{repomatic-7.4.0 → repomatic-7.4.1}/repomatic/__init__.py

@@ -17,5 +17,5 @@
 
 from __future__ import annotations
 
-__version__ = "7.4.0"
-__git_tag_sha__ = "730a6caca5226f9b3c80c238504310c5dad86993"
+__version__ = "7.4.1"
+__git_tag_sha__ = "f3fd0341a6ffbe9f948e78e3270ca30faf2b2459"

{repomatic-7.4.0 → repomatic-7.4.1}/repomatic/binaries_page.py

@@ -56,9 +56,9 @@ import logging
 from pathlib import Path
 
 from click_extra.blocks import replace_region
-from packaging.version import InvalidVersion, Version
 
 from .binary import NUITKA_BUILD_TARGETS
+from .github.releases import parse_release_version
 from .virustotal import VIRUSTOTAL_GUI_URL
 
 TYPE_CHECKING = False
@@ -182,14 +182,6 @@ def _platform_target(name: str) -> str:
     return name
 
 
-def _release_version(tag: str) -> Version | None:
-    """Parse a release tag as a version, or `None` for foreign tag schemes."""
-    try:
-        return Version(tag.removeprefix("v"))
-    except InvalidVersion:
-        return None
-
-
 def _binary_assets(release: ReleaseWithAssets) -> list[ReleaseAsset]:
     """Return the release's compiled binaries, sorted by filename.
 
@@ -261,7 +253,7 @@ def render_chart_section(records: Sequence[ScanRecord]) -> str:
 
     points = []
     for tag, (date, flagged, total) in per_tag.items():
-        version = _release_version(tag)
+        version = parse_release_version(tag)
         if version is None:
             continue
         if total:
@@ -383,7 +375,8 @@ def render_binaries_csv(
     versioned = [
         (version, release)
         for release in releases
-        if not release.draft and (version := _release_version(release.tag)) is not None
+        if not release.draft
+        and (version := parse_release_version(release.tag)) is not None
     ]
     versioned.sort(key=lambda pair: pair[0], reverse=True)
 

{repomatic-7.4.0 → repomatic-7.4.1}/repomatic/cli.py

@@ -105,6 +105,7 @@ from .github.dev_release import (
 from .github.issue import close_open_prs_on_branch
 from .github.pr_body import (
     build_pr_body,
+    build_release_review_steps,
     generate_pr_metadata_block,
     generate_refresh_tip,
     get_template_names,
@@ -4026,6 +4027,24 @@ def pr_body(
         logging.info(f"Auto-detected version: {ver}")
         return ver
 
+    def _resolve_version() -> str:
+        """Resolve the release version from --version, else the bumpversion config."""
+        return version if version is not None else _auto_version()
+
+    # The prepare-release checklist's two review steps share one GitHub
+    # releases lookup; memoize it so both template args reuse a single fetch,
+    # and so no other template pays for it (only prepare-release declares them).
+    review_steps: dict[str, str] = {}
+
+    def _review_step(key: str) -> str:
+        if not review_steps:
+            dev_review, changes_review = build_release_review_steps(
+                Metadata(), _resolve_version()
+            )
+            review_steps["dev_release_review"] = dev_review
+            review_steps["changes_review"] = changes_review
+        return review_steps[key]
+
     cli_extra_args: dict[str, str | None] = {}
     for entry in template_args_cli:
         if "=" not in entry:
@@ -4037,6 +4056,8 @@ def pr_body(
     # Map argument names to their values or callables. CLI-provided extras
     # override built-in flag-driven sources so callers can pass any name.
     arg_sources: dict[str, str | None | Callable[[], str | None]] = {
+        "changes_review": lambda: _review_step("changes_review"),
+        "dev_release_review": lambda: _review_step("dev_release_review"),
         "diff_table": os.getenv("REPOMATIC_DIFF_TABLE", ""),
         "part": part,
         "pr_ref": pr_ref,

{repomatic-7.4.0 → repomatic-7.4.1}/repomatic/data/_release-engine.yaml

@@ -51,7 +51,7 @@ jobs:
       - name: Run repomatic metadata
         id: metadata
         run: >
-          uvx --no-progress 'repomatic==7.4.0' metadata
+          uvx --no-progress 'repomatic==7.4.1' metadata
           --format github-json --output "$GITHUB_OUTPUT"
           new_commits_matrix release_commits_matrix build_targets nuitka_matrix
           nuitka_extras is_python_project package_name current_version
@@ -134,7 +134,7 @@ jobs:
           uv --no-progress sync --frozen ${flags}
       - name: Pre-bake build metadata
         if: contains(matrix.current_version, '.dev')
-        run: uvx --no-progress 'click-extra==8.5.0' prebake all
+        run: uvx --no-progress 'click-extra==8.6.0' prebake all
       - name: Build binary
         id: build-binary
         continue-on-error: true
@@ -158,7 +158,7 @@ jobs:
           # NUITKA_PYTHON_FLAGS holds the entry point's --python-flag (if any),
           # meant to word-split.
           # shellcheck disable=SC2086
-          uvx --no-progress 'repomatic==7.4.0' run nuitka -- \
+          uvx --no-progress 'repomatic==7.4.1' run nuitka -- \
             ${NUITKA_PYTHON_FLAGS} \
             --output-filename="${BIN_NAME}" "${MODULE_PATH}"
       - name: Upload Nuitka crash report
@@ -183,7 +183,7 @@ jobs:
           BIN_NAME: ${{ matrix.bin_name }}
         shell: bash
         run: >
-          uvx --no-progress 'repomatic==7.4.0'
+          uvx --no-progress 'repomatic==7.4.1'
           verify-binary --target "${TARGET}" --binary "${BIN_NAME}"
       - name: Upload binaries
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -327,7 +327,7 @@ jobs:
           CURRENT_VERSION: ${{ matrix.current_version }}
           COMMIT: ${{ matrix.commit }}
         run: >
-          uvx --no-progress 'repomatic==7.4.0' git-tag
+          uvx --no-progress 'repomatic==7.4.1' git-tag
           --tag "v${CURRENT_VERSION}"
           --commit "${COMMIT}"
           --skip-existing
@@ -368,7 +368,7 @@ jobs:
         continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
-        run: uvx --no-progress 'repomatic==7.4.0' sync-dev-release --live --delete
+        run: uvx --no-progress 'repomatic==7.4.1' sync-dev-release --live --delete
       - name: Create GitHub release draft
         # Idempotent: skips if release already exists (e.g. workflow re-run).
         # Notes carry the PyPI availability admonition from the start: baking it
@@ -570,7 +570,7 @@ jobs:
           VIRUSTOTAL_API_KEY: ${{ secrets.VIRUSTOTAL_API_KEY }}
           CURRENT_VERSION: ${{ matrix.current_version }}
         run: >
-          uvx --no-progress 'repomatic==7.4.0' scan-virustotal
+          uvx --no-progress 'repomatic==7.4.1' scan-virustotal
           --tag "v${CURRENT_VERSION}"
           --binaries-dir ./binaries
           --poll
@@ -583,7 +583,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: >
-          uvx --no-progress 'repomatic==7.4.0' sync-binaries
+          uvx --no-progress 'repomatic==7.4.1' sync-binaries
           --repo "${{ github.repository }}"
           --page docs/binaries.md
           --records docs/assets/virustotal-scans.json
@@ -598,7 +598,7 @@ jobs:
           CURRENT_VERSION: ${{ matrix.current_version }}
           DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
         run: >
-          uvx --no-progress 'repomatic==7.4.0' git-commit-push
+          uvx --no-progress 'repomatic==7.4.1' git-commit-push
           --message "Record v${CURRENT_VERSION} binaries"
           --branch "${DEFAULT_BRANCH}"
           docs/binaries.md
@@ -644,5 +644,5 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: >
-          uvx --no-progress 'repomatic==7.4.0' sync-dev-release --live
+          uvx --no-progress 'repomatic==7.4.1' sync-dev-release --live
           --upload-assets release_assets

{repomatic-7.4.0 → repomatic-7.4.1}/repomatic/data/agent-sphinx-docs.md

@@ -545,8 +545,6 @@ Hand-written, but with a strict structure that downstream projects should mirror
 
 7. **Release verification** section showing `gh attestation verify` against the package's own repo, with the `--signer-repo` flag if the release workflow runs as a reusable workflow from another repo. Mirror exactly: a stale flag here breaks reader trust.
 
-8. **Dependencies graph** — a `## Dependencies` section closing the page, embedding `assets/dependencies.mmd` via a plain ```` ```mermaid ```` fence with `:align: center`. The `.mmd` is regenerated by `repomatic update-dep-graph` from `uv.lock`; never hand-edit it. One sentence explains the shapes: boxes hold the directly-declared dependencies of each group, drawn as hexagons; transitive dependencies render outside the boxes as ovals.
-
 Sync rules:
 
 - Re-check the Repology page on every release. New distros get a new tab; dropped distros get the tab removed.
@@ -554,6 +552,14 @@ Sync rules:
 - Version-number references in download URLs must use `releases/latest/download/...`, not pinned tags. Hand-pinned versions in install.md were a long-running source of doc drift.
 - The Try it tab-set's `Specific version` tab does carry a pinned version as an example — that's intentional (it teaches the syntax). From repomatic `v7.4.0` on, the prepare-release freeze step bumps it automatically (`freeze_install_cli_version` rewrites `{package}@X.Y.Z` and `{package}==X.Y.Z` pins in `docs/install.md`); hand-bumping is only needed on repos pinned to older release engines.
 
+### `packaging.md`: distribution and dependency reference
+
+A maintainer/packager-facing page. Every project carries the **dependency graph** here; projects distributed through package managers add their per-channel build instructions on the same page.
+
+**Dependencies graph** — a `## Dependencies` section embedding `assets/dependencies.mmd` via a plain ```` ```mermaid ```` fence with `:align: center`. The `.mmd` is regenerated by `repomatic update-dep-graph` from `uv.lock`; never hand-edit it. One sentence explains the shapes: boxes hold the directly-declared dependencies of each group, drawn as hexagons; transitive dependencies render outside the boxes as ovals.
+
+The graph used to close `install.md`; it moved here so the install page stays end-user-focused while packager-facing material lives on one page. `meta-package-manager` is the reference: its `packaging.md` renders the graph above a full per-distro build catalog.
+
 ## Standard page roster
 
 A Sphinx site for a CLI/library project should converge on a predictable page set. Downstream repos that mirror this roster get free coherence with every other repo following the convention, and readers learn one navigation pattern.
@@ -565,7 +571,7 @@ Primary toctree (user-facing), in this order:
 01. `install` — § Recipes › `install.md`. Always first.
 02. `cli` — § Recipes › `cli.md`. CLIs only.
 03. `configuration` — § Recipes › `configuration.md`. Projects with `[tool.X]` schema.
-04. `dependencies` — Dependency policy page (version-specifier rules, floor-comment conventions, audit procedures). The project's own dependency graph does not get a page of its own: it lives in `install.md`'s `## Dependencies` section (see § Recipes › `install.md`, step 8).
+04. `dependencies` — Dependency policy page (version-specifier rules, floor-comment conventions, audit procedures). The project's own dependency graph is not a page of its own: it renders in `packaging.md`'s `## Dependencies` section (see § Recipes › `packaging.md`).
 05. `tool-runner` — Only when the project ships a `repomatic run`-style tool runner.
 06. `workflows` — Only when the project publishes reusable workflows.
 07. `test-matrix` — Only when the project documents its CI test-matrix composition.
@@ -579,14 +585,15 @@ Development toctree, in this order:
 02. `upstream-development` — Project-internal release process. Mark `(upstream maintainers only)` in the page heading so readers know this is not for consumers.
 03. `operation-contracts` — Optional, for projects with formal automated-operation contracts.
 04. `API <{package}>`, `tests` — Autodoc API pages: the `API <...>` entry aliases the package's root autodoc page, `tests` covers the test-suite package. Both keep plain octicon-free headings (see Title octicons below).
-05. `binaries` — Standalone-executables catalog written by the repomatic binaries pipeline. Only for projects compiling Nuitka binaries; a maintainer-facing reference, so it belongs here rather than in the primary toctree (end users reach the same downloads through `install.md`'s `## Executables` section).
-06. `genindex`, `modindex` — Sphinx-generated index and module index.
-07. `changelog` — Reference the root changelog via `{include} ../changelog.md` so the file stays single-sourced.
-08. `changelog-archive` — Only when `[tool.repomatic] changelog.archive-location` points into `docs/`.
-09. `todolist` — `sphinx.ext.todo` output. Drop this entry when the project has no TODOs.
-10. `code-of-conduct`, `license` — `{include}` from root files; never duplicate the text.
-11. `GitHub repository <https://...>` — External link as the last entry.
-12. `Funding <https://github.com/sponsors/...>` — External link if the project accepts funding.
+05. `packaging` — Distribution and dependency reference (see § Recipes › `packaging.md`). Every project renders its dependency graph here; projects distributed through package managers add their per-channel build instructions alongside it. Maintainer/packager-facing, so it sits in Development.
+06. `binaries` — Standalone-executables catalog written by the repomatic binaries pipeline. Only for projects compiling Nuitka binaries; a maintainer-facing reference, so it belongs here rather than in the primary toctree (end users reach the same downloads through `install.md`'s `## Executables` section).
+07. `genindex`, `modindex` — Sphinx-generated index and module index.
+08. `changelog` — Reference the root changelog via `{include} ../changelog.md` so the file stays single-sourced.
+09. `changelog-archive` — Only when `[tool.repomatic] changelog.archive-location` points into `docs/`.
+10. `todolist` — `sphinx.ext.todo` output. Drop this entry when the project has no TODOs.
+11. `code-of-conduct`, `license` — `{include}` from root files; never duplicate the text.
+12. `GitHub repository <https://...>` — External link as the last entry.
+13. `Funding <https://github.com/sponsors/...>` — External link if the project accepts funding.
 
 Page-shape rules that apply across the roster:
 
@@ -600,6 +607,8 @@ Page-shape rules that apply across the roster:
   | `add-packaging-channel.md` | `git-merge`            |
   | `agents.md`                | `dependabot`           |
   | `architectures.md`         | `cpu`                  |
+  | `augmentations.md`         | `plus-circle`          |
+  | `bar-plugin.md`            | `plug`                 |
   | `benchmark.md`             | `trophy`               |
   | `binaries.md`              | `desktop-download`     |
   | `carapace.md`              | `chevron-right`        |
@@ -614,9 +623,12 @@ Page-shape rules that apply across the roster:
   | `configuration.md`         | `sliders`              |
   | `context.md`               | `database`             |
   | `contributing.md`          | `git-pull-request`     |
+  | `cooldown.md`              | `history`              |
   | `decorators.md`            | `mention`              |
   | `dependencies.md`          | `package-dependencies` |
   | `detection.md`             | `pulse`                |
+  | `dump.md`                  | `file-moved`           |
+  | `duplicates.md`            | `stack`                |
   | `envvar.md`                | `pin`                  |
   | `execution.md`             | `play`                 |
   | `falsehoods.md`            | `copilot-warning`      |
@@ -626,15 +638,18 @@ Page-shape rules that apply across the roster:
   | `license.md`               | `law`                  |
   | `logging.md`               | `log`                  |
   | `man-page.md`              | `repo`                 |
+  | `managers.md`              | `file-submodule`       |
   | `mkdocs.md`                | `markdown`             |
   | `myst-docstrings.md`       | `pencil`               |
   | `operation-contracts.md`   | `tasklist`             |
+  | `overrides.md`             | `pin`                  |
   | `packaging.md`             | `package-dependents`   |
   | `parameters.md`            | `tasklist`             |
   | `platforms.md`             | `codespaces`           |
   | `pygments.md`              | `file-code`            |
   | `pytest.md`                | `meter`                |
   | `releasing.md`             | `rocket`               |
+  | `sbom.md`                  | `verified`             |
   | `screenshots.md`           | `device-camera`        |
   | `security.md`              | `shield-lock`          |
   | `shells.md`                | `chevron-right`        |
@@ -642,6 +657,7 @@ Page-shape rules that apply across the roster:
   | `sphinx.md`                | `book`                 |
   | `spinner.md`               | `sync`                 |
   | `styling.md`               | `typography`           |
+  | `sudo.md`                  | `key`                  |
   | `table.md`                 | `table`                |
   | `telemetry.md`             | `broadcast`            |
   | `terminals.md`             | `terminal`             |
@@ -754,7 +770,7 @@ Strictness flags:
 Theme assets and OpenGraph:
 
 - `html_logo = "assets/logo-square.svg"` and `html_favicon = "assets/favicon.svg"` are the canonical paths. Both files live under `docs/assets/` and ship as SVG so the Furo theme's dark-mode swap works without a separate asset bundle. The `/brand-assets` skill is the canonical producer of these files: it manages the SVG sources (favicon, square logo, banner, social banner), exports light/dark PNG variants, and wires the new files into `docs/conf.py`. When `html_logo`/`html_favicon` are missing or out of date, run `/brand-assets` instead of editing the assets by hand.
-- `ogp_image = "assets/banner-social-light.png"` — set when the project has a banner asset for social previews. Without `ogp_image`, `sphinxext.opengraph` falls back to the favicon, which scales poorly. Always pair it with `ogp_site_url = f"https://{github_user}.github.io/{project_id}/"`: the image path is resolved against the site URL, not the page, and without one the raw HTML carries a relative `og:image` that social crawlers cannot follow (verified on repomatic's own built pages). The PNG is exported from `assets/banner-social.svg` by the `/brand-assets` skill (which also produces the dark variant for dark-mode social cards on platforms that support them).
+- `ogp_image` must be an **absolute** URL to the committed PNG on the GitHub raw host — `f"https://raw.githubusercontent.com/{github_user}/{project_id}/main/docs/assets/banner-social-light.png"` — never a site-relative `assets/...` path. `docs/assets/` is not copied into the built site (it is neither in `html_static_path` nor referenced by any doc body, so Sphinx's image collector never picks it up), so a relative `ogp_image` resolves against `ogp_site_url` to a URL that 404s for the social crawlers that only ever see the raw HTML. Set it when the project has a banner asset; without `ogp_image`, `sphinxext.opengraph` falls back to the favicon, which scales poorly. Still define `ogp_site_url = f"https://{github_user}.github.io/{project_id}/"` for the page-level `og:url` tag. The PNG is exported from `assets/banner-social.svg` by the `/brand-assets` skill (which also produces the dark variant for dark-mode social cards on platforms that support them).
 - The Furo `announcement` banner template across this lineage references the same `github_user` constant defined at the top of `conf.py`. Rebuilding the announcement string locally inside `html_theme_options` avoids a per-theme override layer.
 
 Pruning checklist before merging any `conf.py` change: