docs: clarify homepage smoke test setup

Author: mschwar

CURRENT_STATE.md

@@ -13,6 +13,7 @@ This repository is a small GitHub Pages static site that publishes a single oral
 - A committed `Gemfile` and `.ruby-version` pin the GitHub Pages toolchain for local builds.
 - `Figure2-Teeth_v4.1.pdf` and `scripts/render_heatmap.py` provide a reproducible source-to-raster path for `oral-health-heatmap.png`.
 - `scripts/check_homepage.py` provides a non-UI smoke test for the rendered homepage.
+- `scripts/check_homepage.py` now explains the fresh-checkout default: `_site/index.html` is generated by `bundle exec jekyll build`, or callers can pass a rendered HTML path or live URL.
 - 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`.
@@ -25,6 +26,7 @@ This repository is a small GitHub Pages static site that publishes a single oral
 - Provenance refinement branch QA passed on 2026-05-19: `docs/heatmap-provenance.md` clearly states that the raw/analysis-ready source dataset is not published, distinguishes PDF/figure-to-PNG regeneration from full data-to-figure regeneration, and documents the Windows/MiKTeX `pdftoppm` temp/log permission blocker.
 - `python scripts/validate_repo.py` passed on 2026-05-19 with only the known stale `README.CRAWL.md` warning.
 - `python -m compileall scripts` passed on 2026-05-19.
+- Homepage smoke-test documentation fix passed `python scripts/check_homepage.py https://mschwar.github.io/data-visualization/` on 2026-05-19.
 - A local homepage QA snapshot passed `python scripts/check_homepage.py` and was then captured at desktop and mobile widths in a browser-rendered view.
 - The browser captures showed the heatmap image, page heading, and download link in the expected positions with no visible layout regressions.
 - Historical artifact governance passed non-UI QA: `python scripts/validate_repo.py`, Python script compilation, policy-doc discoverability checks, and `_config.yml` exclusion checks.
@@ -37,7 +39,7 @@ This repository is a small GitHub Pages static site that publishes a single oral
 | `python scripts/validate_repo.py` | Repo validation | Pass with warning about stale `README.CRAWL.md` |
 | `python -m compileall scripts` | Python syntax/import compilation check | Pass |
 | `python scripts/render_heatmap.py` | Heatmap rebuild | Currently blocked locally by Windows/MiKTeX `pdftoppm` temp/log permission errors |
-| `python scripts/check_homepage.py` | Homepage smoke test | Requires `_site/index.html` from a Jekyll build, or an explicit rendered HTML path or URL |
+| `python scripts/check_homepage.py` | Homepage smoke test | Requires `_site/index.html` from a Jekyll build; on fresh checkout, pass an explicit rendered HTML path or URL |
 | `Invoke-WebRequest https://mschwar.github.io/data-visualization/` | Live site verification | 200 OK |
 | `bundle exec jekyll build` | Local Jekyll build | Not run in this environment because Ruby was unavailable at audit time |
 
@@ -73,5 +75,6 @@ The pinned build path is now committed in-repo, so local build instructions are
 
 ## Immediate Next Moves
 
-1. Track the follow-on fixes listed in [docs/agentic-first-buildout-plan.md](docs/agentic-first-buildout-plan.md).
-2. Keep historical artifacts documented in [docs/historical-artifacts.md](docs/historical-artifacts.md).
+1. QA `feat/homepage-smoke-docs`, update handoff docs with the QA result, then merge it to `main`.
+2. Build the deployment check or badge feature from the main buildout sequence after this branch merges.
+3. Keep historical artifacts documented in [docs/historical-artifacts.md](docs/historical-artifacts.md).

README.md

@@ -65,7 +65,7 @@ bundle exec jekyll build
 python scripts/check_homepage.py
 ```
 
-You can also pass an explicit rendered HTML path or live URL:
+On a fresh checkout, `python scripts/check_homepage.py` expects `_site/index.html`, which is generated by `bundle exec jekyll build` and is not committed. If you have not built the site locally, pass an explicit rendered HTML path or the live site URL instead:
 
 ```bash
 python scripts/check_homepage.py _site/index.html

docs/agentic-first-buildout-plan.md

@@ -68,14 +68,16 @@ Start the remaining buildout here:
 
 ### 4. Provenance refinement
 
-- Status: next.
+- Status: merged to main.
 - Goal: tighten the provenance story around the source PDF, the published PNG, and any constraints on regeneration.
 - Merge boundary: documentation only.
 - Verification: non-UI link/file validation.
 - Why fourth: it depends on the regeneration path already being committed.
 
 ### 5. Deployment check or badge
 
+- Status: next in the main buildout sequence.
+
 - Goal: add a lightweight live-deploy indicator or a Pages verification step if the repo still needs one.
 - Merge boundary: CI/docs only.
 - Verification: explicit non-UI command or GitHub Actions status.
@@ -87,6 +89,7 @@ These are known missing or non-working items discovered during repo audit. Keep
 
 ### A. Homepage Smoke-Test Documentation Fix
 
+- Status: implemented on `feat/homepage-smoke-docs`; pending QA and merge.
 - Problem: `python scripts/check_homepage.py` fails on a fresh checkout until `_site/index.html` exists.
 - Fix: document that the command requires `bundle exec jekyll build` first, or pass an explicit rendered HTML path or live URL.
 - Verification: run `python scripts/check_homepage.py <rendered-html-or-url>`.

scripts/check_homepage.py

@@ -11,6 +11,12 @@
 
 ROOT = Path(__file__).resolve().parents[1]
 DEFAULT_SOURCE = ROOT / "_site" / "index.html"
+DEFAULT_SOURCE_HELP = (
+    "Default homepage HTML is generated by Jekyll and is not committed. "
+    "Run `bundle exec jekyll build` first, or pass an explicit rendered HTML path "
+    "or URL such as `python scripts/check_homepage.py "
+    "https://mschwar.github.io/data-visualization/`."
+)
 EXPECTED_TITLE = "Oral Health Heatmap | Matthew Schwartz Data Visualization"
 EXPECTED_HEADING = "Oral Health Heatmap"
 EXPECTED_IMAGE_ALT = (
@@ -77,6 +83,8 @@ def main() -> int:
         html = load_html(args.source)
     except FileNotFoundError as exc:
         print(f"Homepage HTML not found: {exc}", file=sys.stderr)
+        if Path(args.source) == DEFAULT_SOURCE:
+            print(DEFAULT_SOURCE_HELP, file=sys.stderr)
         return 1
 
     errors = check_homepage(html)