docs: reconcile action READMEs and templates with the shipped code

Docs-vs-code mismatch from the 2026-07 maintenance audit: READMEs, templates and guides document inputs that do not exist, omit inputs that do, and point at a removed action. Distinct from the container/version drift in #106.

Documented features that do not exist

QUICK-REFERENCE documents an alias input preview-netlify does not accept — the "Preview with Custom URL" section at docs/QUICK-REFERENCE.md:156-165 is fictional: the action's only inputs are netlify-auth-token, netlify-site-id, build-dir, lectures-dir (preview-netlify/action.yml:5-18), and the alias is hardcoded --alias="pr-${PR_NUMBER}" at :76. Fix: delete and retitle, or add the input.

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

build-lectures/README.md points at a removed action — :160 says "LaTeX packages (use setup-latex action)"; no such directory exists, and README.md:22 calls it replaced by setup-environment. The mechanism is setup-environment with install-latex: 'true' (demonstrated at :272). The seven-row inputs table at build-lectures/README.md:22-28 omits failure-artifact-name (build-lectures/action.yml:38, consumed at :179) — the only guard against artifact-name collisions in multi-build jobs.

Docs behind behaviour changes

README and ARCHITECTURE still say restore-jupyter-cache "never saves" — README.md:54 and docs/ARCHITECTURE.md:70. save-cache has existed since v0.8.0 (restore-jupyter-cache/action.yml:34, gating steps at :61, :80, :134) and has worked since v0.9.0 (#104). CHANGELOG.md:300-303 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 uploads on success; v0.8.0 made it failure-only — partly fixed: prose at build-jupyter-cache/README.md:161-164 and the input description at build-jupyter-cache/action.yml:23 are now correct. Still wrong: the ASCII flow diagram at build-jupyter-cache/README.md:142 puts "Upload artifact" under "4a. ALL PASSED", and the inputs row at :24 reads a bare "Upload _build as artifact". Real gate: build-jupyter-cache/action.yml:349 (inputs.upload-artifact == 'true' && steps.status.outputs.all-passed != 'true') — no build-cache-<run_id> artifact from a green run.

Examples that fail for adopters

Workflow examples omit permissions:, unlike the templates they mirror (templates/cache.yml:50-53) — build-jupyter-cache/README.md:84-87 now declares contents: read / issues: write / packages: read (v0.11.0, #122), but preview-netlify/README.md:83-85 and preview-cloudflare/README.md:86-88 declare no block at all, and the root quick-start at README.md:69-71 declares only contents: read / packages: read yet ends with preview-netlify (README.md:86), which calls github.rest.issues.createComment at preview-netlify/action.yml:179 using github.token (:110) — so it needs pull-requests: write and 403s without it.

Templates and 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 in 18 files, vs @v7 in .github/workflows/test-actions.yml:91. Two @v5 stragglers at docs/MIGRATION-GUIDE.md:190 and :265 survive a plain v4 → v7 replace.

The dependabot guard against that is a no-op — adding - "/templates" to the github-actions directories list at .github/dependabot.yml:78-86 bumps nothing: per the file's own comment at :73-76, that ecosystem scans .github/workflows/ for / and otherwise only the named directory's own action.yml; templates/ has neither, and its three actions/checkout@v4 pins are the only third-party pins there. Guard repo-side: a test-harness assertion that templates/ third-party pins match .github/workflows/.

templates/publish.yml's release-asset block cannot work as shipped — the commented block at :111-116 warns at :113 that it "Only works when triggered by a tag push", but the triggers at :19-25 are push-to-main plus workflow_dispatch, no tag trigger, and permissions at :43 are contents: read — the unmentioned blocker being the missing contents: write. Fix: document both, or state that release assets are unsupported.

build-jupyter-cache forces install-latex for pdflatex but exposes no latex-requirements-file input — build-jupyter-cache/action.yml:153 passes install-latex: ${{ steps.parse-builders.outputs.run-pdflatex }} into setup-environment with no requirements-file input, so the callee default applies and setup-environment/action.yml:151-159 hard-fails (::error::, exit 1) when that file is missing; no tracked example exists in the repo, yet templates/cache.yml:44-48 advertises the standard-runner path. Standard (non-container) mode only.

Smaller items

• cname writes a CNAME file the native Pages deploy path does not read — publish-gh-pages/action.yml:60-64 writes it into build-dir; the deploy chain is configure-pages@v6 (:68) → upload-pages-artifact@v5 (:71) → deploy-pages@v5 (:78). templates/publish.yml:12 says configure the custom domain in Settings → Pages while :109 offers cname:. Confirm, then either drop it and point mentions at Settings → Pages, or keep it with a ::warning:: that it has no effect.
• Cache key and path — setup-environment/README.md:132 and docs/QUICK-REFERENCE.md:180 render the standard-mode key as conda-{os}-{hash(environment.yml)}-{version}, dropping the {environment-name} and py{python-version} segments of the real key at setup-environment/action.yml:134, so it reads as if a Python bump will not invalidate the cache. setup-environment/README.md:133 also lists /home/runner/conda_pkgs_dir, which setup-environment/action.yml:133 does not cache — only $CONDA/envs/{environment-name}.
• Fabricated "LaTeX cache hit" log line — docs/QUICK-REFERENCE.md:286, in the sample log block at :284-288; no LaTeX caching exists in the repo. docs/MIGRATION-GUIDE.md:439 repeats it in the git commit -m message migrators copy ("Adds caching for conda, pip, and LaTeX") — a one-word deletion.
• README.md:207 says test via @main; CONTRIBUTING.md:121 says reference your branch, and CONTRIBUTING.md:57-62 shows a v0 force-move that README's step 5 (README.md:209) omits.

Folding in #99, and sequencing

#99 — its "Pages 404?" snippet at docs/QUICK-REFERENCE.md:312-316 recommends contents: write; same file, same fix, so close it here. Only that half is live: the cache-key half is mis-attributed — docs/MIGRATION-GUIDE.md:244 describes build-jupyter-cache's key (really build-{env-hash}-{update-hash}-{run-id}, built at build-jupyter-cache/action.yml:95), not setup-environment's, whose key is the genuinely wrong one covered above.

Sequencing — PLAN item 10 (PLAN.md:80) deletes docs/README.md and shrinks QUICK-REFERENCE.md to a one-screen link table. Four items here — the alias: recipe, the cache-key row, the fabricated log line and #99's 404 snippet — live in QUICK-REFERENCE.md, so make that trim decision first.

Checklist

• permissions: block in build-jupyter-cache/README.md — done in v0.11.0 (#122)
• permissions: blocks in the three remaining examples: preview-netlify/README.md:83-85, preview-cloudflare/README.md:86-88, and pull-requests: write at README.md:69-71
• checkout@v4 → @v7 across templates/ and docs (36 sites in 18 files), plus the two @v5 stragglers at docs/MIGRATION-GUIDE.md:190,265
• Add a repo-side pin-drift check for templates/ (the dependabot /templates entry is a no-op)
• 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" in README.md:54 and docs/ARCHITECTURE.md:70
• Failure-only artifact wording: flow diagram build-jupyter-cache/README.md:142 and inputs row :24
• Document contents: write (and the tag trigger) on templates/publish.yml's release-asset block
• Resolve cname
• latex-requirements-file passthrough + example file
• @main → @v0 in containers/quantecon-build/README.md:60 — the last @main usage example in any .md
• Theme version 0.18.0 → 0.21.0 — containers/quantecon/README.md:116 vs the pin at containers/quantecon/environment.yml:17
• Correct the setup-environment cache key and path in both docs sites
• Remove the fabricated LaTeX-caching claims (QUICK-REFERENCE.md:286, MIGRATION-GUIDE.md:439)
• Reconcile the README/CONTRIBUTING testing-and-release instructions
• Fix #99 while in QUICK-REFERENCE.md

Start with the checklist and sequencing note in this issue, then inspect the cited READMEs, templates, action.yml files, workflows, and PLAN.md. Resolve the QUICK-REFERENCE trim decision first, verify each documented input, permission, pin, trigger, cache behavior, and artifact claim against shipped code, and add the requested template pin-drift check. Done means the remaining checklist items and #99 are reconciled without contradicting the referenced action behavior.