Skip to content

CLAUDE.md

Latest commit

 

History

History
75 lines (57 loc) · 3.37 KB

CLAUDE.md

File metadata and controls

75 lines (57 loc) · 3.37 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the lab manual for the Contextual Dynamics Laboratory (CDL) at Dartmouth College. It's a LaTeX document using the Tufte-book class that describes lab policies, member responsibilities, and research approach. The repo also contains CDL Bot (cdl_bot/), a Slack bot that automates onboarding, offboarding, and term meeting scheduling.

Build Commands

Compile the PDF:

./compile.sh

Runs latex 5x (for cross-references/index), then pdflatex, and cleans up intermediate files. Requires a LaTeX distribution (brew install --cask mactex on macOS).

Run bot tests:

pytest tests/test_onboarding/ -v   # All tests
pytest tests/test_onboarding/test_scheduling.py -v  # Scheduling only (no API keys needed)

Tests use real API calls (no mocks). Tests skip automatically when credentials are missing.

Run CDL Bot:

pip install -e .     # First time only
cdl-bot start        # Start (idempotent)
cdl-bot stop         # Stop (idempotent)
cdl-bot restart      # Stop + start
cdl-bot status       # Show running state
cdl-bot logs         # Tail log file

Requires .env in cdl_bot/ with Slack tokens, GitHub PAT, and optionally Google/Anthropic credentials.

Project Structure

  • lab_manual.tex — Main document source (single file, all content)
  • lab_manual.pdf — Compiled output (committed to repo)
  • compile.sh — PDF build script
  • tufte.cfg — TeX4ht configuration for HTML generation
  • tufte-book.cls, tufte-common.def — Custom Tufte template files (do not modify casually)
  • toc.js, checklist.js, lab-manual.css — HTML version enhancements (TOC nav, interactive checklist, custom styling)
  • cdl_bot/ — CDL Bot (Slack automation, see cdl_bot/README.md)
  • tests/test_onboarding/ — Bot tests (real API calls, no mocks)
  • pyproject.toml — Package config, installs cdl-bot CLI

CI/CD

  • compile-latex.yml — On PRs touching .tex files: compiles LaTeX, posts error comment and closes PR on failure
  • build-html.yml — On push to master: converts LaTeX to HTML via tex4ht, deploys to GitHub Pages at contextlab.github.io/lab-manual

LaTeX Conventions

Custom commands in lab_manual.tex:

  • \marginnote{} — Margin notes (TASK items and NOTEs)
  • \newthought{} — Section introductions
  • \ourschool — Expands to "Dartmouth College"
  • \director, \coordinator — Lab director references
  • Links use dartmouthgreen color (RGB: 0, 105, 62)

Workflow Notes

After editing lab_manual.tex:

  1. Run ./compile.sh to regenerate the PDF
  2. Verify the PDF looks correct (check TOC links, margin notes positioning)
  3. Commit both the .tex source and updated .pdf

The HTML version is auto-generated by CI — no manual build needed.

Key Gotchas

  • lab_manual.tex is gitignored (the .tex line in .gitignore) — this is intentional to avoid accidental commits of intermediate build state. The file IS tracked by git despite the gitignore entry.
  • The CI will close PRs that fail LaTeX compilation — always test locally with ./compile.sh first.
  • Onboarding bot credentials go in cdl_bot/.env (gitignored). Never commit tokens or service account JSON files.
  • Bot tests require running from the repo root so cdl_bot is importable as a package.