[gaborbernat]

The README had grown past 1,500 lines, so a maintainer adopting these workflows in another repository had to read nearly all of it to find the parts that mattered. Now the README answers three questions quickly: what is available, how a typical repository wires it up, and how to pin versions. The first is a table covering every workflow and Action, each with a one-line purpose, the permissions its caller must grant, and a link. The second shows the check and prepare-release caller files in full and links to the rest.

The reference material now lives in one page per area: the release flow, preparation, publishing, pull request checks, maintenance pull requests, locked tools, security scanning, JetBrains, the pre-commit mirror, and LaTeX. Each page opens with when and why to use its pieces, then lists inputs, outputs, permissions and secrets in tables, and calls out the pitfalls. The release flow page has a diagram that runs from the pull request dry run through dispatch, tagging and publishing, with colours readable in both light and dark themes. A new troubleshooting page is keyed by the error text a maintainer sees in the job log.

Every fact from the old README carries over. While moving it, I checked each input against the workflow and Action definitions and fixed where the docs had drifted. For example, the maintenance workflow does not expose the pull request number to callers, the notes workflow needs a release-notes lock group, and the tag push always targets main. The Scorecard workflow and several inputs that were never listed are now documented. A new test fails when a workflow or Action input, output or secret is missing from its docs section, so this drift cannot build up silently again.

#55, which merged first, makes release preparation install only the changelog formatter's hook, and the docs describe that behaviour.

Practices adopted from well-documented action repositories:

• Usage before reference. Each section starts with a copy-paste snippet that shows its permissions:, as in setup-uv, gh-action-pypi-publish and the SLSA generic builder. Permissions are what callers most often get wrong with reusable workflows, because a caller can only narrow them.
• Required permissions in one place. The catalog has a caller-grants column, as setup-python and codeql-action give each permission its own section.
• Inputs kept in sync with the YAML. actions/checkout regenerates its input docs from action.yml. A name check in the test suite gets most of that benefit without moving 36 interfaces into generated blocks.
• Pinning and breaking changes. The pinning section links to GitHub's guidance on full-SHA pins and to every breaking-changes section in the changelog, following setup-python and scorecard-action. This repository has no moving major tags, so the section says so.
• Troubleshooting and FAQ, as in setup-uv and scorecard-action.
• Stated scope. A "What stays in your repository" section works like gh-action-pypi-publish's non-goals.

I did not adopt two practices. Separate READMEs beside each action.yml, as the reviewdog action repos keep, would scatter 36 units whose value lies in how they combine. Version "What's new" blocks at the top of the README would duplicate the changelog.