Skip to content

Commit f254190

Browse files
jeremymanningclaude
jeremymanning
and
claude
committed
Update documentation and run validation (Phase 6)
- Updated CLAUDE.md: added reconcile command, submodule setup, cleaned up auto-generated sections - Updated AGENTS.md and scripts/AGENTS.md: added new scripts to structure and WHERE TO LOOK tables - All 192 tests pass, pre-push check passes, reconciliation dry-run shows 57 discrepancies (18 flagged for review) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent da73305 commit f254190

4 files changed

Lines changed: 120 additions & 10 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ contextlab.github.io/
2020
├── scripts/ # Python build system (see scripts/AGENTS.md)
2121
├── images/ # Assets: people/, publications/, software/, research/, news/
2222
├── documents/ # CV files (JRM_CV.tex → .pdf, .html)
23+
├── lab-manual/ # Git submodule (ContextLab/lab-manual)
2324
└── tests/ # pytest suite for build system
2425
```
2526

@@ -29,7 +30,8 @@ contextlab.github.io/
2930
|------|----------|-------|
3031
| Add publication | `data/publications.xlsx` | Auto-builds via GitHub Actions |
3132
| Add team member | `scripts/onboard_member.py` | Processes photo, generates bio, updates CV |
32-
| Offboard member | `scripts/offboard_member.py` | Moves to alumni, updates CV |
33+
| Offboard member | `scripts/offboard_member.py` | Moves to alumni, updates CV + lab-manual |
34+
| Reconcile people | `scripts/reconcile_people.py` | Three-way sync: people.xlsx ↔ CV ↔ lab-manual |
3335
| Add software | `data/software.xlsx` | |
3436
| Add news | `data/news.xlsx` | Thumbnail in `images/news/` |
3537
| Update CV | `documents/JRM_CV.tex` | Auto-compiles to PDF+HTML |

‎CLAUDE.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Static website for the Contextual Dynamics Lab at Dartmouth College. Hosted on GitHub Pages at [context-lab.com](https://context-lab.com). Content pages (publications, people, software, news) are **auto-generated** from Excel spreadsheets via a Python build system — never edit the root HTML for those pages directly.
8+
9+
## Commands
10+
11+
```bash
12+
# Install dependencies
13+
pip install -r requirements-build.txt
14+
15+
# Validate spreadsheet data
16+
cd scripts && python validate_data.py
17+
18+
# Build all content pages (publications, people, software, news)
19+
cd scripts && python build.py
20+
21+
# Build CV (requires XeLaTeX + Dartmouth Ruzicka fonts)
22+
cd scripts && python build_cv.py
23+
24+
# Run full test suite
25+
python -m pytest tests/ -v
26+
27+
# Run a single test file
28+
python -m pytest tests/test_build_publications.py -v
29+
30+
# Pre-push validation (validation + build + tests)
31+
cd scripts && python pre_push_check.py
32+
33+
# Local dev server
34+
python3 -m http.server 8000
35+
36+
# Add hand-drawn borders to images
37+
python scripts/add_borders.py image.png images/publications/
38+
python scripts/add_borders.py photo.jpg images/people/ --face
39+
40+
# Onboard new member (from scripts/ dir)
41+
python onboard_member.py "First Last" --rank "grad student" --photo headshot --skip-llm
42+
43+
# Offboard member to alumni (from scripts/ dir)
44+
python offboard_member.py "member name" --end-year 2025
45+
46+
# Reconcile people across website, CV, and lab-manual
47+
cd scripts && python reconcile_people.py --dry-run # report only
48+
cd scripts && python reconcile_people.py # apply auto-fixes
49+
50+
# Initialize lab-manual submodule (required for reconciliation)
51+
git submodule update --init
52+
```
53+
54+
## Architecture
55+
56+
### Content Pipeline
57+
58+
```
59+
data/*.xlsx → scripts/build_*.py → root *.html (auto-generated)
60+
↑
61+
templates/*.html (markers like <!-- PUBLICATIONS_PAPERS -->)
62+
```
63+
64+
Each `build_*.py` follows the same pattern:
65+
1. Load spreadsheet with `utils.load_spreadsheet_all_sheets()`
66+
2. Generate HTML fragments
67+
3. Inject into template via `utils.inject_content(template, output, {"MARKER": html})`
68+
69+
### Key Directories
70+
71+
| Directory | Purpose |
72+
|-|-|
73+
| `data/` | Source spreadsheets (publications.xlsx, people.xlsx, software.xlsx, news.xlsx) + Dartmouth fonts |
74+
| `templates/` | HTML templates with `<!-- MARKER -->` injection points |
75+
| `scripts/` | Python build system, validation, onboarding/offboarding tools |
76+
| `tests/` | pytest suite — conftest.py adds `scripts/` to sys.path |
77+
| `documents/` | CV source (JRM_CV.tex) and generated outputs (PDF, HTML) |
78+
| `css/style.css` | Single stylesheet with CSS variables at top |
79+
| `js/main.js` | All JS components (9 init functions) |
80+
| `lab-manual/` | Git submodule — [ContextLab/lab-manual](https://github.com/ContextLab/lab-manual) (init with `git submodule update --init`) |
81+
82+
### CV Pipeline
83+
84+
`documents/JRM_CV.tex` → `scripts/build_cv.py` + `scripts/extract_cv.py` (custom LaTeX→HTML parser) → `documents/JRM_CV.pdf` + `documents/JRM_CV.html`
85+
86+
### GitHub Actions
87+
88+
- **build-content.yml**: Triggers on changes to `data/`, `templates/`, `scripts/`. Validates, builds, runs tests, auto-commits regenerated HTML.
89+
- **build-cv.yml**: Triggers on changes to `documents/JRM_CV.tex`, CV scripts, or `css/cv.css`. Compiles LaTeX, runs tests, auto-commits PDF+HTML.
90+
91+
## Critical Rules
92+
93+
- **Never edit auto-generated root HTML** (`publications.html`, `people.html`, `software.html`, `news.html`) — edit `data/*.xlsx` or `templates/*.html` instead
94+
- **Never use `!important`** in CSS without explicit justification
95+
- **Never add inline styles** to templates — use CSS classes
96+
- **Always run tests before pushing**: `python -m pytest tests/ -v`
97+
- **All headings are lowercase** via `text-transform: lowercase` in CSS
98+
99+
## Design System
100+
101+
- **Colors**: `--primary-green: rgb(0, 112, 60)`, `--bg-green: rgba(0, 112, 60, 0.2)`, `--dark-text: rgba(0, 0, 0, 0.7)`
102+
- **Font**: Nunito Sans, 300 weight body, 14px base, 1.7 line-height
103+
- **Images**: 500x500px with hand-drawn green borders (use `scripts/add_borders.py`), face-detect cropping for people photos (`--face`)
104+
- **Forms**: Formspree backend — endpoint in form `action` attribute

‎scripts/AGENTS.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ scripts/
1919
├── citation_utils.py # Publication citation formatting
2020
├── add_borders.py # Image processing (hand-drawn borders)
2121
├── onboard_member.py # Add new lab members (with LLM bio generation)
22-
└── offboard_member.py # Move members from active to alumni
22+
├── offboard_member.py # Move members from active to alumni
23+
├── parse_lab_manual.py # Parse lab_manual.tex members chapter + write helpers
24+
└── reconcile_people.py # Three-way sync: people.xlsx ↔ CV ↔ lab-manual
2325
```
2426

2527
## WHERE TO LOOK
@@ -32,8 +34,10 @@ scripts/
3234
| Fix validation | `validate_data.py` | Required fields, file existence checks |
3335
| Fix CV parsing | `extract_cv.py` | LaTeX commands → HTML |
3436
| Fix image borders | `add_borders.py` | Uses MediaPipe for face detection |
35-
| Onboard lab member | `onboard_member.py` | Processes photo, generates bio, updates spreadsheet + CV |
36-
| Offboard lab member | `offboard_member.py` | Moves member to alumni, updates CV |
37+
| Onboard lab member | `onboard_member.py` | Processes photo, generates bio, updates spreadsheet + CV + lab-manual |
38+
| Offboard lab member | `offboard_member.py` | Moves member to alumni, updates CV + lab-manual |
39+
| Reconcile people data | `reconcile_people.py` | Three-way sync: people.xlsx ↔ CV ↔ lab-manual |
40+
| Parse lab-manual members | `parse_lab_manual.py` | Extract/write members in lab_manual.tex |
3741

3842
## CONVENTIONS
3943

‎specs/001-people-labmanual-sync/tasks.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,14 @@
103103

104104
**Purpose**: Documentation and final validation
105105

106-
- [ ] T029 [P] Update `CLAUDE.md`: add reconcile command, submodule setup instructions, note lab-manual submodule under architecture
107-
- [ ] T030 [P] Update `AGENTS.md`: add `reconcile_people.py` and `parse_lab_manual.py` to structure and WHERE TO LOOK table
108-
- [ ] T031 [P] Update `scripts/AGENTS.md`: add new scripts to structure, commands, and conventions sections
106+
- [x] T029 [P] Update `CLAUDE.md`: add reconcile command, submodule setup instructions, note lab-manual submodule under architecture
107+
- [x] T030 [P] Update `AGENTS.md`: add `reconcile_people.py` and `parse_lab_manual.py` to structure and WHERE TO LOOK table
108+
- [x] T031 [P] Update `scripts/AGENTS.md`: add new scripts to structure, commands, and conventions sections
109109
- [ ] T032 [P] Update `README.md`: add submodule setup instructions, reconciliation documentation, updated onboard/offboard examples
110-
- [ ] T033 Run `python reconcile_people.py --dry-run` against real production data and review the discrepancy report
110+
- [x] T033 Run `python reconcile_people.py --dry-run` against real production data and review the discrepancy report
111111
- [ ] T034 Run `python reconcile_people.py` to apply auto-fixes to real data (after T033 review)
112-
- [ ] T035 Run full test suite: `python -m pytest tests/ -v` — all tests MUST pass
113-
- [ ] T036 Run `cd scripts && python pre_push_check.py` for full pre-push validation
112+
- [x] T035 Run full test suite: `python -m pytest tests/ -v` — all tests MUST pass
113+
- [x] T036 Run `cd scripts && python pre_push_check.py` for full pre-push validation
114114

115115
---
116116

0 commit comments

Comments
 (0)