feat: add homepage smoke test

Author: mschwar

.DS_Store

@@ -0,0 +1,32 @@
+name: Validate
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run repository validation
+        run: python scripts/validate_repo.py
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3.4"
+          bundler-cache: true
+
+      - name: Build the Jekyll site
+        run: bundle exec jekyll build
+
+      - name: Smoke test homepage
+        run: python scripts/check_homepage.py

.github/workflows/validate.yml

@@ -0,0 +1,6 @@
+.DS_Store
+Thumbs.db
+_site/
+Gemfile.lock
+__pycache__/
+*.pyc

.gitignore

@@ -0,0 +1 @@
+3.3.4

.ruby-version

@@ -0,0 +1,85 @@
+# AGENTS
+
+## How To Orient In This Repo
+
+Start with `CURRENT_STATE.md` for the current audit summary, then read `docs/agentic-first-buildout-plan.md` for the branch/PR/QA loop, then read `README.md` for the public-facing intent. The canonical site content lives in `index.md`, the site metadata lives in `_config.yml`, and the primary visualization asset is `oral-health-heatmap.png`.
+
+## Canonical Source-Of-Truth Files
+
+- `CURRENT_STATE.md`: current repository truth and known risks
+- `docs/agentic-overhaul/2026-05-audit.md`: fuller audit, maturity scores, and backlog
+- `README.md`: public overview of the project
+- `index.md`: rendered GitHub Pages content
+- `_config.yml`: site title, description, and theme config
+- `Gemfile` and `.ruby-version`: pinned local Jekyll toolchain
+- `assets/css/style.scss.css`: hand-authored site styling
+- `oral-health-heatmap.png`: published visualization asset
+- `Figure2-Teeth_v4.1.pdf`: committed source figure for the PNG
+- `scripts/render_heatmap.py`: source-to-raster rebuild script
+- `scripts/check_homepage.py`: homepage smoke test script
+- `docs/heatmap-provenance.md`: provenance and rebuild notes
+
+## Commands To Run Before And After Changes
+
+Before changes:
+
+- `git status --short`
+- `python scripts/validate_repo.py`
+- `python scripts/render_heatmap.py` if you touch the heatmap source artifact or rebuild notes
+- `python scripts/check_homepage.py` if you touch the homepage render or nav
+
+After changes:
+
+- `python scripts/validate_repo.py`
+- `bundle exec jekyll build`
+- `git status --short`
+
+The repo now pins the local Jekyll toolchain with `Gemfile` and `.ruby-version`. Do not claim build parity unless you have run the pinned build command successfully.
+
+## Generated Vs. Hand-Authored Files
+
+Hand-authored:
+
+- `README.md`
+- `index.md`
+- `_config.yml`
+- `Gemfile`
+- `.ruby-version`
+- `assets/css/style.scss.css`
+- `CURRENT_STATE.md`
+- `docs/agentic-overhaul/2026-05-audit.md`
+- `AGENTS.md`
+- `docs/heatmap-provenance.md`
+- `docs/agentic-first-buildout-plan.md`
+- `scripts/render_heatmap.py`
+- `scripts/check_homepage.py`
+
+Generated or historical artifact:
+
+- `README.CRAWL.md`: historical crawl output with stale machine-local metadata; do not treat as canonical truth
+
+## Data, Citation, And Provenance Rules
+
+- Do not invent dataset provenance, participant counts, or publication claims beyond what is already supported in committed files.
+- If you add provenance notes, tie them to already-present citation material or newly committed source artifacts.
+- If the image can be regenerated, document the real pipeline; do not guess at unpublished steps.
+- Keep the source PDF and rebuild script in sync with `oral-health-heatmap.png`.
+
+## Accessibility And Documentation Expectations
+
+- Preserve meaningful alt text for the main image and any future visual assets.
+- Keep README and `CURRENT_STATE.md` aligned when commands or repo structure change.
+- Favor small, explicit documentation updates over implied behavior.
+
+## Safe-Change Rules
+
+- Keep the repo lightweight; avoid introducing heavy tooling unless the site grows.
+- Do not hand-edit generated artifacts if a real generator is introduced later.
+- Prefer edits that preserve GitHub Pages compatibility.
+- Avoid deleting historical artifacts unless their role is documented and the removal is clearly safe.
+
+## Known Project-Specific Traps
+
+- `README.CRAWL.md` includes stale machine-local paths and a directory count from another environment.
+- The repo now pins the Jekyll toolchain, so local Pages rendering can be verified once Ruby is installed.
+- The visualization image is committed, and the committed source PDF plus rebuild script provide the regeneration path.

AGENTS.md

@@ -0,0 +1,62 @@
+# Current State
+
+Audit date: 2026-05-19
+
+## Purpose
+
+This repository is a small GitHub Pages static site that publishes a single oral-health heatmap and explanatory narrative for the Tsimane population of Bolivia. The site is centered on one visualization asset (`oral-health-heatmap.png`), one page of written interpretation (`index.md`), and lightweight Jekyll/Minima configuration for deployment through GitHub Pages.
+
+## Confirmed Working Pieces
+
+- Core content files exist: `README.md`, `index.md`, `_config.yml`, `oral-health-heatmap.png`, and `assets/css/style.scss.css`.
+- The site content includes descriptive alt text for the primary visualization.
+- 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.
+- 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.
+
+## Existing Commands
+
+| Command | Purpose | Result |
+| --- | --- | --- |
+| `python scripts/validate_repo.py` | Repo validation | Pass with warning about stale `README.CRAWL.md` |
+| `python scripts/render_heatmap.py` | Heatmap rebuild | Produces the published 1700 x 2200 PNG from the committed PDF source at 200 DPI |
+| `python scripts/check_homepage.py` | Homepage smoke test | Verifies the rendered homepage title, heading, heatmap image, alt text, download link, and the absence of README.CRAWL.html |
+| `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 |
+
+The pinned build path is now committed in-repo, so local build instructions are canonical even though this environment did not have Ruby installed when the audit started.
+
+## Important Files And Directories
+
+- `README.md`: public-facing repo overview and live site link
+- `index.md`: main GitHub Pages content page
+- `_config.yml`: GitHub Pages/Jekyll site metadata
+- `assets/css/style.scss.css`: hand-authored theme overrides
+- `oral-health-heatmap.png`: primary visualization asset
+- `Figure2-Teeth_v4.1.pdf`: source PDF for the published heatmap
+- `scripts/render_heatmap.py`: reproducible heatmap rebuild script
+- `scripts/check_homepage.py`: homepage smoke test script
+- `docs/heatmap-provenance.md`: provenance notes and rebuild command
+- `scripts/validate_repo.py`: lightweight validation spine
+- `docs/agentic-overhaul/2026-05-audit.md`: detailed audit and backlog
+- `AGENTS.md`: contributor and agent operating guide
+
+## Stale Or Conflicting Docs And Metadata
+
+- `README.CRAWL.md` contains a machine-local path (`/Users/mschwar/...`) and a historical directory crawl snapshot. It is useful as a historical artifact only and should not be treated as canonical documentation.
+- The repo now references a pinned local Ruby/Jekyll toolchain, so local build instructions are canonical from the repo itself.
+
+## Known Risks
+
+- Local GitHub Pages rendering is not reproducible from committed tooling in the current environment.
+- Local build execution still depends on having Ruby installed on the host.
+- The historical source dataset that fed the original figure is still not published in this repo.
+- `README.CRAWL.md` remains as a historical artifact but is excluded from the public site.
+
+## Immediate Next Moves
+
+1. Follow [docs/agentic-first-buildout-plan.md](docs/agentic-first-buildout-plan.md) for the next feature branch.
+2. Keep `scripts/render_heatmap.py` and `Figure2-Teeth_v4.1.pdf` in sync if the figure changes.
+3. Run `python scripts/check_homepage.py` against `_site/index.html` after a local build if you need a homepage smoke check.

CURRENT_STATE.md

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+ruby "3.3.4"
+
+gem "github-pages", "232", group: :jekyll_plugins
+gem "webrick"

Figure2-Teeth_v4.1.pdf

@@ -2,6 +2,12 @@
 
 This repository showcases a data visualization project designed to represent the complete oral health status of the Tsimane population of Bolivia. The heatmap synthesizes over 32,000 data points from 1,176 individuals into a single, intuitive image, revealing complex patterns of dental health across age, sex, and anatomy.
 
+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`.
+
+For the branch/PR/QA loop used by future agents, see `docs/agentic-first-buildout-plan.md`.
+
 ---
 
 ## ▶️ View the Live Project
@@ -27,6 +33,38 @@ A 5-point color scale indicates the health status of each tooth, from healthy (b
 *   `index.md`: The main content file for the GitHub Pages site, written in Markdown.
 *   `oral-health-heatmap.png`: The high-resolution image of the data visualization.
 *   `_config.yml`: The configuration file that applies the visual theme to the GitHub Pages site.
+*   `Figure2-Teeth_v4.1.pdf`: The committed source figure used to regenerate the PNG.
+*   `Gemfile`: The pinned GitHub Pages and Ruby toolchain.
+*   `.ruby-version`: The pinned Ruby runtime for local builds.
+*   `scripts/validate_repo.py`: Lightweight repository validation for future contributors and agents.
+*   `docs/agentic-first-buildout-plan.md`: Branch/PR/QA loop and feature sequencing guide.
+*   `scripts/render_heatmap.py`: Rebuild script for the published heatmap PNG.
+*   `scripts/check_homepage.py`: Smoke test for the rendered homepage HTML.
+*   `docs/heatmap-provenance.md`: Source artifact and rebuild notes.
+
+## Validate The Repo
+
+Run:
+
+```bash
+python scripts/validate_repo.py
+python scripts/check_homepage.py
+```
+
+This checks for required files, obvious broken local references, key site metadata, committed OS junk files, and the rendered homepage shape.
+
+## Rebuild Locally
+
+This repository pins Ruby 3.3.4 and `github-pages` 232, matching the current GitHub Pages dependency set. To rebuild the site and the heatmap locally:
+
+```bash
+bundle install
+bundle exec jekyll build
+bundle exec jekyll serve --baseurl=""
+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.
 
 ## Publication Context
 

Gemfile

@@ -1,3 +1,12 @@
 theme: minima
 title: Matthew Schwartz | Data Visualization
-description: A showcase of data analysis and visualization projects.
+description: A showcase of data analysis and visualization projects.
+exclude:
+  - AGENTS.md
+  - CURRENT_STATE.md
+  - Figure2-Teeth_v4.1.pdf
+  - Gemfile
+  - Gemfile.lock
+  - README.CRAWL.md
+  - docs/
+  - scripts/