Write a real README for the shared workflows

[nickhart]

The previous README was GitHub's two-line default, for a repo three sites depend on — and which also renders on the org profile page.

Structure

Workflows first, since that is what the repo contains and why anyone arrives here: a table of the three, then a copy-pasteable caller for each with its real inputs and secrets. Both examples were diffed against the actual callers rather than written from memory, so they match character for character.

Then a section for the two mistakes that each cost an afternoon, because neither is discoverable from the error message:

• permissions must sit on the calling job, not the top level of the caller's file, or the token falls back to the repo default and the pull request lookup 403s — the email then links the pull request list instead of the pull request. Includes the tell: read the GITHUB_TOKEN Permissions group in the run log. Also records that passing GITHUB_TOKEN down as a secret does not help and is rejected outright.
• A called workflow cannot discover its own version. github.job_workflow_sha does not exist; workflow_sha and workflow_ref both describe the caller. Hence shared-ref.

Plus the two "do not" rules that are easy to get backwards, both learned the hard way:

• no paths: filter on mdx-check, because a required check that never runs blocks a pull request with nothing to click
• prose-check must not be required, because it is built to pass even when it finds something

Versioning

Says plainly that v1 is mutable — a release boundary, not an immutability guarantee — and that SHA-pinning is the answer if that matters.

Projects

md2do and post-inbox only, per your call that the others are not ready to feature.

Verified: all four relative links and the one anchor resolve; both caller examples match production.

🤖 Generated with Claude Code