docs: reconcile action READMEs and templates with the shipped code

[mmcky]

Action READMEs, templates and guides document inputs that do not exist, omit inputs that do, and point at a removed action. Found in the 2026-07 maintenance audit. Distinct from the container/version drift tracked separately in this milestone — this is docs-vs-code mismatch.

Documented features that do not exist

QUICK-REFERENCE documents an alias input preview-netlify does not accept — docs/QUICK-REFERENCE.md:164. The action declares four inputs at action.yml:5-18; the alias is hardcoded at :76. The whole "Preview with Custom URL" section describes a feature that does not exist. Fix: delete the section and retitle, or add the input.

MIGRATION-GUIDE's collab.yml snippet passes two build-lectures inputs that never existed — docs/MIGRATION-GUIDE.md:378. build-html and cache-workflow produce "Unexpected input" warnings and a silent default HTML build; the cache-restore intent is dropped entirely. Fix: builder: 'html', source-dir: 'lectures', plus a preceding restore-jupyter-cache@v0 step.

build-lectures/README.md points at a removed action — README.md:160 says "use setup-latex action"; no such directory exists. The mechanism is setup-environment with install-latex: 'true', demonstrated in this same file at :281. The inputs table at :20-28 also omits failure-artifact-name (action.yml:38), which is the only way to avoid artifact-name collisions in a multi-build job.

Behaviour that changed and the docs did not

README and ARCHITECTURE still say restore-jupyter-cache "never saves" — README.md:54 and docs/ARCHITECTURE.md:70. The save-cache input has existed since v0.8.0 (action.yml:34), and CHANGELOG.md:59 claims the docs were fixed — only the action README and QUICK-REFERENCE were. Fix: "Read-only by default; optional PR-scoped save-cache".

Docs say the _build artifact is uploaded on success; v0.8.0 made it failure-only — build-jupyter-cache/README.md:132, :24, and templates/README.md:41. action.yml:273 gates the upload on all-passed != 'true', and the input's own description already says so. Maintainers go looking for a build-cache-<run_id> artifact from green runs that is never produced.

Copy-paste examples that will fail for adopters

Workflow examples omit permissions:, unlike the templates they mirror — build-jupyter-cache/README.md:79, preview-netlify/README.md:83, preview-cloudflare/README.md:85, README.md:69-71. The templates get this right (templates/cache.yml:50-53); the action READMEs declare nothing, and the root README quick-start declares contents/packages but omits pull-requests: write even though the example ends with preview-netlify, which calls issues.createComment. On a read-only-default org these fail with an opaque 403; on a write-default org they silently over-privilege.

Templates and all docs recommend actions/checkout@v4 while the repo's own workflows are on @v7 — templates/ci.yml:47, templates/cache.yml:57, templates/publish.yml:54 — 36 occurrences across 18 files. Root cause: .github/dependabot.yml:78-86 lists every action directory but not /templates, so these will never be bumped automatically and every migrated repo starts three majors behind. Fix: bump to @v7 across templates/ and the docs, and add - "/templates" to the github-actions directories list so it does not recur.

templates/publish.yml's release-asset block cannot work as shipped — templates/publish.yml:114: no tag trigger and contents: read.

build-jupyter-cache forces install-latex for pdflatex but exposes no latex-requirements-file input — action.yml:130-136. setup-environment then hard-fails at :152 if latex-requirements.txt is missing, and no example of that file exists anywhere in the repo — yet templates/cache.yml:44-48 explicitly advertises the standard-runner path. Fix: plumb the input through and ship a commented templates/latex-requirements.txt.

Smaller items in the same files

• cname writes a CNAME file the native Pages deploy path does not read — publish-gh-pages/action.yml:61-64 vs the deploy chain at :68-78. The repo contradicts itself: templates/publish.yml:12 says configure it in Settings while :109 offers cname:. Confirm the behaviour, then either drop the input and point all six mentions at Settings → Pages, or keep it and emit a ::warning:: that it has no effect.
• @main → @v0 — containers/quantecon-build/README.md:60
• quantecon-book-theme (0.18.0) → (0.21.0) — containers/quantecon/README.md:116
• Correct the cache key and path — setup-environment/README.md:132, docs/QUICK-REFERENCE.md:180
• Replace the fabricated "LaTeX cache hit" log block — docs/QUICK-REFERENCE.md:283-288, docs/MIGRATION-GUIDE.md:439
• README.md:207 says test via @main; CONTRIBUTING.md:103 says reference your branch, and :57-63 shows a v0 force-move that README's step 5 omits

Worth folding in

#99 — the QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions. Same file, same kind of fix; closing it here saves a second pass.

Checklist

• permissions: blocks in the four workflow examples
• checkout@v4 → @v7 across templates/ and docs
• Add - "/templates" to dependabot.yml
• Delete the alias: recipe
• Fix the collab.yml snippet inputs
• setup-latex → setup-environment; add the failure-artifact-name row
• "Never saves" → "read-only by default"
• Failure-only artifact wording
• Resolve cname
• latex-requirements-file passthrough + example file
• Fix docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99 while in QUICK-REFERENCE.md