Cache actions: key correctness, stale read-only README, and H6 build-key triage

[mmcky]

Correctness + doc issues in the restore/build cache actions.

• H4 — Dead primary cache key. restore-jupyter-cache/action.yml:64 & :79: when save-cache != true, the primary key ends in -00000000, which never matches a key saved by build-jupyter-cache (uses github.run_id). It only works via restore-keys prefix fallback; the exact-match path is dead and the "Requested Key" report is misleading. Use the prefix as the key directly.
• H5 — README still says "read-only, never saves". restore-jupyter-cache/README.md:7 contradicts the save-cache input added in 0.5.2 (action.yml:34-37). Update the README's Design Philosophy + inputs table and docs/QUICK-REFERENCE.md.
• L21 — Unused path input. action.yml:10-13 declares path (default _build), but the save side hardcodes _build (build-jupyter-cache/action.yml:255). Overriding path restores to the wrong place. Remove or document the constraint.

✅ Decision (resolved 2026-06-16) — H6: keep the env-only key, document it

The build (_build) cache key stays env-hash only (build-jupyter-cache/action.yml:74-78) — by design, not a bug. It is a stable warm-start baseline from main; freshness is already handled downstream by jupyter-cache (content-addressed per notebook), Sphinx incremental rebuilds, and the weekly cold build-jupyter-cache run. Adding a lectures/**/*.md hash would miss the cache on essentially every PR (every PR edits some .md) and defeat the warm-start for no correctness gain.

The one real exposure — Sphinx incremental does not delete outputs for removed/renamed sources — is benign in practice: orphaned pages aren't in _toc.yml or linked from any current page, so they're unreachable through navigation, and the weekly cold rebuild clears them. No stale pages observed to date. (Both PR-preview and publish build incrementally from the cache, and that has been reliable.)

• H6 (docs) — document that the build-cache key is intentionally env-only: explain the warm-start design and the jupyter-cache + Sphinx-incremental + weekly-rebuild safety net in the build-jupyter-cache / restore-jupyter-cache READMEs and the caching section of docs/ARCHITECTURE.md.

Related: #18 (container-mode caching).

Filed from the 2026-06-16 technical review; H6 resolved 2026-06-16.

[mmcky]

H6 resolved: keep the build-cache key env-only and document it.

Discussed the trade-off — a content hash would invalidate the cache on nearly every PR and defeat the warm-start, while freshness is already covered by jupyter-cache (per-notebook content addressing), Sphinx incremental, and the weekly cold rebuild. The only exposure (orphaned HTML from deleted/renamed lectures) is unreachable in navigation (not in _toc.yml, not linked) and cleared by the weekly rebuild; none observed in practice, and publish building incrementally from cache has been reliable.

So H6 becomes a documentation task (added to the checklist above), not a code change. H4/H5/L21 are unaffected — still straightforward fixes.