docs: refine heatmap provenance

Author: mschwar

CURRENT_STATE.md

@@ -16,6 +16,7 @@ This repository is a small GitHub Pages static site that publishes a single oral
 - The Jekyll config excludes `vendor/`, so the bundled gem tree is kept out of the public site build.
 - The validate workflow uses Node 24-compatible `actions/checkout@v6` and `actions/setup-python@v6`.
 - `README.CRAWL.md` is explicitly documented as a retained historical artifact in `docs/historical-artifacts.md`.
+- The heatmap provenance boundary is explicit: this repo supports PDF-to-PNG regeneration, but the raw source dataset is not published here.
 - A repo-local validation command now checks required files, local links, key config values, and tracked OS junk.
 - The live GitHub Pages deployment returned HTTP 200 and served the expected page content in this session.
 
@@ -68,6 +69,6 @@ The pinned build path is now committed in-repo, so local build instructions are
 
 ## Immediate Next Moves
 
-1. Start provenance refinement from [docs/agentic-first-buildout-plan.md](docs/agentic-first-buildout-plan.md).
+1. QA the provenance refinement branch by confirming the provenance boundary is discoverable in README, CURRENT_STATE, and `docs/heatmap-provenance.md`.
 2. Track the follow-on fixes listed in [docs/agentic-first-buildout-plan.md](docs/agentic-first-buildout-plan.md).
 3. Keep historical artifacts documented in [docs/historical-artifacts.md](docs/historical-artifacts.md).

README.md

@@ -4,7 +4,7 @@ This repository showcases a data visualization project designed to represent the
 
 This is a small GitHub Pages static site. The repo currently publishes one primary page (`index.md`) and one primary visualization asset (`oral-health-heatmap.png`).
 
-The repo also pins a local GitHub Pages build path (`Gemfile` and `.ruby-version`) and keeps the committed source figure (`Figure2-Teeth_v4.1.pdf`) with a rebuild script in `scripts/render_heatmap.py`.
+The repo also pins a local GitHub Pages build path (`Gemfile` and `.ruby-version`) and keeps the committed source figure (`Figure2-Teeth_v4.1.pdf`) with a rebuild script in `scripts/render_heatmap.py`. The raw source dataset behind the figure is not published in this repository.
 
 For the branch/PR/QA loop used by future agents, see `docs/agentic-first-buildout-plan.md`.
 
@@ -85,6 +85,8 @@ python scripts/render_heatmap.py
 
 The heatmap PNG is regenerated from `Figure2-Teeth_v4.1.pdf` at 200 DPI. The rendered pixels match the published PNG; only PNG encoder metadata can differ.
 
+Current local caveat: on this Windows environment, the heatmap rebuild command is blocked by MiKTeX `pdftoppm` temp/log permission errors. See [`docs/heatmap-provenance.md`](docs/heatmap-provenance.md) for the exact provenance boundary and rebuild status.
+
 ## Publication Context
 
 This visualization was created as part of the research published in:

docs/heatmap-provenance.md

@@ -1,10 +1,16 @@
 # Oral Health Heatmap Provenance
 
-The published heatmap is derived from the committed source figure PDF and a single rasterization step.
+The published heatmap in this repository is reproducible from the committed source figure PDF through a single rasterization step.
 
-- Source figure: [Figure2-Teeth_v4.1.pdf](../Figure2-Teeth_v4.1.pdf)
-- Published raster: [oral-health-heatmap.png](../oral-health-heatmap.png)
-- Rebuild script: [scripts/render_heatmap.py](../scripts/render_heatmap.py)
+- Source figure available in this repo: [Figure2-Teeth_v4.1.pdf](../Figure2-Teeth_v4.1.pdf)
+- Published raster available in this repo: [oral-health-heatmap.png](../oral-health-heatmap.png)
+- Rebuild script available in this repo: [scripts/render_heatmap.py](../scripts/render_heatmap.py)
+
+## Provenance Boundary
+
+This repository does not currently publish the raw or analysis-ready source dataset behind the original heatmap. The committed PDF is the earliest source artifact available here.
+
+That means this repo supports figure-to-PNG regeneration, not full data-to-figure regeneration. Do not claim that the complete underlying dataset or statistical pipeline is reproducible from this repository unless those materials are added later.
 
 ## Rebuild Command
 
@@ -13,3 +19,7 @@ python scripts/render_heatmap.py
 ```
 
 The source PDF is letter-sized and the rebuild path exports the image at 200 DPI. That reproduces the same 1700 x 2200 pixel image content as the committed PNG. PNG encoder metadata may differ between exporters, but the pixels match.
+
+## Current Local Rebuild Blocker
+
+On this Windows environment, `python scripts/render_heatmap.py` is currently blocked by MiKTeX `pdftoppm` permission errors while writing log/temp output under `AppData\Local`. The script and source artifact remain committed, but local verification of the rebuild command requires either a working `pdftoppm` installation or a future script change that routes temporary output through a known writable repo-local path.

scripts/validate_repo.py

@@ -143,6 +143,10 @@ def check_readme(warnings: list[str]) -> None:
         warnings.append("README.md does not document the historical artifact policy.")
     if "README.CRAWL.md" not in readme:
         warnings.append("README.md does not mention the retained historical crawl snapshot.")
+    if "raw source dataset" not in readme:
+        warnings.append("README.md does not document the unpublished raw source dataset boundary.")
+    if "MiKTeX" not in readme or "pdftoppm" not in readme:
+        warnings.append("README.md does not document the current Windows heatmap rebuild caveat.")
     crawl = ROOT / "README.CRAWL.md"
     if crawl.exists():
         crawl_text = crawl.read_text(encoding="utf-8")
@@ -152,6 +156,20 @@ def check_readme(warnings: list[str]) -> None:
             )
 
 
+def check_provenance(errors: list[str]) -> None:
+    provenance = (ROOT / "docs" / "heatmap-provenance.md").read_text(encoding="utf-8")
+    required_phrases = [
+        "raw or analysis-ready source dataset",
+        "figure-to-PNG regeneration",
+        "not full data-to-figure regeneration",
+        "MiKTeX",
+        "pdftoppm",
+    ]
+    for phrase in required_phrases:
+        if phrase not in provenance:
+            errors.append(f"docs/heatmap-provenance.md should document `{phrase}`.")
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description="Validate the repository structure and key content.")
     parser.add_argument(
@@ -169,6 +187,7 @@ def main() -> int:
     check_config(errors)
     check_index(errors)
     check_local_links(errors)
+    check_provenance(errors)
     check_readme(warnings)
 
     if errors: