docs(ci): say what the database cache key does, not what it means

The key is hashFiles over data/**, parser/** and datasets.json, so it
invalidates by path. Both the guide and the workflow comment described it by
intent instead — "a web or docs change restores the databases" — which the
previous commit disproved by paying for a full 348 MB rebuild to fix a comment
in datasets.json and a sentence in parser/README.md.

Over-invalidating is the safe direction, and narrowing the globs would mean
remembering to extend them for every future path that can change a database.
Record the trade rather than making it.

.github/workflows/deploy-pages.yml

@@ -99,8 +99,13 @@ jobs:
       # Parsing 348 MB of spreadsheets is the slowest part of the job, and its
       # output is a pure function of the inputs in the key: the source files,
       # the parser (schema, transforms, configs) and the registry the row-count
-      # and size guards read. Anything else — web code, docs, workflow — cannot
-      # change a database, so those pushes restore one instead of rebuilding.
+      # and size guards read. A push touching none of them — web code, docs/,
+      # this workflow — restores a database instead of rebuilding one.
+      #
+      # The key is by path rather than by meaning, so it over-invalidates: a
+      # comment in datasets.json or a word in parser/README.md pays for a full
+      # rebuild. Narrowing the globs would trade minutes on a docs push for
+      # having to remember every future path that can change a database.
       #
       # Exact matches only, with no restore-keys: a near-miss here would mean
       # publishing a database built from different inputs than the commit says.

docs/deployment-guide.md

@@ -27,11 +27,16 @@ pull-request run cancel an in-flight `main` deploy while every check stayed
 green.
 
 The database build dominates the runtime: roughly 348 MB of Excel to parse. It
-is cached in Actions, keyed on `data/**`, `parser/**` and `datasets.json`, so
-only a change to the sources, the parser or the registry pays for it — a web or
-docs change restores the databases instead. There are no `restore-keys`: a
-near-miss would publish databases built from inputs the commit does not
-describe.
+is cached in Actions, keyed on `data/**`, `parser/**` and `datasets.json`, so a
+push that touches none of those — web code, `docs/`, the workflow — restores the
+databases instead of rebuilding them. There are no `restore-keys`: a near-miss
+would publish databases built from inputs the commit does not describe.
+
+The key is by path, not by what the change means, so it over-invalidates: a
+comment in `datasets.json` or a word in `parser/README.md` costs a full rebuild
+though neither can move a row. That is the safe direction to be wrong in, and
+narrowing the globs would mean remembering to extend them for every future path
+that *can* change a database. The cost is minutes on the occasional docs push.
 
 ## Resulting URLs