Clean up cache actions: honest restore key + caching docs (#34)

[mmcky]

Addresses all four items in #34 — correctness + documentation cleanup in the cache actions. No behavioural change to caching; one dead code path removed and the caching design documented.

Changes

H4 — honest restore key (code)

restore-jupyter-cache read-only mode set the primary key to …-00000000, which can never match a saved key (the saver always suffixes with ${github.run_id}). It silently fell through to restore-keys prefix matching. Now it uses the content/env prefix as the key directly:

• exec: jupyter-cache-{hash}-
• build: build-{env}-{update}-

Same restore result (prefix match), but the logged "Requested Key" is now truthful and the dead exact-match path is gone.

H5 — README no longer claims strictly read-only (docs)

Documented the optional save-cache input (added in 0.5.2) in the Design Philosophy section and the inputs table — PR-scoped saving that GitHub Actions confines to the PR branch.

L21 — path constraint documented (docs)

path must match where build-jupyter-cache saves (_build). Documented the constraint in the input description and the README table rather than leaving a knob that silently restores to the wrong location. (No caller passes path: today; removing it outright would be a cleaner but breaking follow-up.)

H6 — build-cache key design documented (docs)

Per the decision recorded in #34, documented that the build-cache key is intentionally environment-only: _build is a warm-start baseline, and freshness is handled by jupyter-cache (per-notebook, content-addressed), Sphinx incremental rebuilds, and the weekly cold rebuild. A content hash would miss on nearly every PR and force a cold rebuild for no correctness gain. Added to both cache action READMEs and the caching section of docs/ARCHITECTURE.md.

Verification

• restore-jupyter-cache/action.yml validated as YAML; no -00000000 remains.
• Restore behaviour is unchanged (prefix matching was already the only working path).

Closes #34

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refines the cache actions’ restore-key behavior and updates documentation to better reflect the intended caching design (prefix-based restores; build cache keyed by environment only).

Changes:

• Removed the non-functional “exact match” restore key in read-only mode by using the appropriate key prefixes directly.
• Updated restore-jupyter-cache documentation to describe save-cache, path constraints, and the environment-only build-cache key rationale.
• Added architecture/docs rationale explaining why _build cache is intentionally environment-keyed (not lecture-content-keyed).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
restore-jupyter-cache/README.md	Updates design philosophy, inputs table, and documents build-key rationale.
restore-jupyter-cache/action.yml	Makes read-only restore key “honest” by using the prefix key directly; clarifies path description.
docs/ARCHITECTURE.md	Documents the environment-only build-cache key rationale at the architecture level.
CHANGELOG.md	Records the restore-key correction and documentation updates under Unreleased.
build-jupyter-cache/README.md	Adds a short explanation for why the build-cache key omits lecture-content hashing.