Merge pull request #183 from ContextLab/feature/onboarding-bot

Add CDL onboarding Slack bot (#181)

Author: jeremymanning

.gitignore

@@ -28,3 +28,47 @@ html_test/
 
 # Playwright MCP screenshots
 .playwright-mcp/
+
+# CDL Onboarding Bot
+scripts/onboarding/.env
+scripts/onboarding/output/
+scripts/onboarding/*.json
+scripts/onboarding/secrets/
+scripts/onboarding/data/
+*.credentials.json
+service-account*.json
+google-credentials.json
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# Claude session notes
+notes/

CLAUDE.md

@@ -4,36 +4,82 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.
+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 a **Slack onboarding bot** (`scripts/onboarding/`) that automates member on/offboarding.
 
 ## Build Commands
 
 **Compile the PDF:**
 ```bash
 ./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).
 
-This runs `latex` multiple times (for cross-references and index), then `pdflatex`, and cleans up intermediate files. Requires a LaTeX distribution (e.g., `brew install --cask mactex` on macOS).
+**Run onboarding bot tests:**
+```bash
+# No API keys needed
+pytest tests/test_onboarding/test_models.py -v
+pytest tests/test_onboarding/test_image_service.py -v
+
+# Requires GITHUB_TOKEN
+pytest tests/test_onboarding/test_github_service.py -v
+
+# Requires ANTHROPIC_API_KEY
+pytest tests/test_onboarding/test_bio_service.py -v
+
+# All tests
+pytest tests/test_onboarding/ -v
+```
+Tests use real API calls (no mocks). Tests skip automatically when credentials are missing.
 
-**HTML version:** The HTML version is automatically generated via GitHub Actions when changes are pushed to master. No manual build is needed. The workflow uses make4ht (TeX4ht) with `tufte.cfg` configuration to convert to tufte-css styled HTML.
+**Run the onboarding bot:**
+```bash
+python -m scripts.onboarding.bot
+```
+Requires `.env` in `scripts/onboarding/` with Slack tokens, GitHub PAT, and optionally Google/Anthropic credentials.
 
 ## Project Structure
 
-- `lab_manual.tex` - Main document source (single file containing all content)
-- `lab_manual.pdf` - Compiled output (committed to repo)
-- `tufte.cfg` - TeX4ht configuration for HTML generation
-- `tufte-book.cls`, `tufte-common.def`, `tufte-handout.cls` - Custom Tufte template files
-- `lab_logo/` - Lab logo images (PNG, PDF)
-- `resources/` - Additional resources (cheatsheets, cluster tutorials)
-- `.github/workflows/` - CI/CD workflows (LaTeX validation, HTML generation)
+- `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)
+- `scripts/onboarding/` — Slack onboarding bot (see architecture below)
+- `tests/test_onboarding/` — Bot tests (real API calls, no mocks)
+
+### Onboarding Bot Architecture
+
+```
+scripts/onboarding/
+├── bot.py              # Entry point, Slack app setup
+├── config.py           # Environment/config management
+├── handlers/
+│   ├── onboard.py      # /cdl-onboard slash command
+│   ├── approval.py     # Admin approval workflow (interactive messages)
+│   ├── offboard.py     # /cdl-offboard slash command
+│   └── workflow_step.py # Slack Workflow Builder custom steps
+├── models/
+│   └── onboarding_request.py  # Data models
+└── services/
+    ├── github_service.py    # GitHub org invitations
+    ├── calendar_service.py  # Google Calendar sharing
+    ├── image_service.py     # Photo border processing (Pillow)
+    └── bio_service.py       # Bio editing via Claude API
+```
+
+## 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
 
-The document uses several custom commands defined in `lab_manual.tex`:
-- `\marginnote{}` - For margin notes (TASK items and NOTEs)
-- `\newthought{}` - For section introductions
-- `\ourschool` - Expands to "Dartmouth College"
-- `\director`, `\coordinator` - Lab director references
+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
@@ -42,3 +88,12 @@ 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 `scripts/onboarding/.env` (gitignored). Never commit tokens or service account JSON files.
+- Bot tests require running from the repo root so `scripts.onboarding` is importable as a package.

lab_manual.pdf

@@ -163,7 +163,7 @@
 
 \newcommand{\director}{Jeremy}
 \newcommand{\coordinator}{\director}
-\newcommand{\meeting}{\href{https://context-lab.youcanbook.me}{YouCanBook.me}}
+\newcommand{\meeting}{\href{https://context-lab.com/scheduler}{context-lab.com/scheduler}}
 
 \cleardoublepage
 \chapter{Introduction}\label{ch:intro} % Adding an asterisk leaves out this chapter from the table of contents
@@ -207,13 +207,7 @@ \chapter{Introduction}\label{ch:intro} % Adding an asterisk leaves out this chap
 
 \newthought{What should you do if you don't understand something?}
 
-\noindent \marginnote{\texttt{TASK:} If you haven't used \LaTeX~before
-  (i.e., the document formatting language in which this manual is
-  written), you'll want to
-  \href{https://www.latex-project.org/get/}{download \LaTeX} and take
-  a look at
-  \href{https://www.latex-tutorial.com/tutorials/quick-start/}{this
-    ``quick start'' tutorial}.} If you don't understand something in
+\noindent If you don't understand something in
 this manual, \textit{ask another lab
   member for help}.  Every member of the lab brings their own unique
 knowledge base, training, life experiences, and perspectives.
@@ -224,10 +218,14 @@ \chapter{Introduction}\label{ch:intro} % Adding an asterisk leaves out this chap
 inconsistency!
 
 \marginnote{\texttt{TASK:} When you are done reading this manual and
-  carrying out all required tasks, please fill out the signature page,
-  sign it (electronically), and email a PDF (of just the signature
-  page) to
-  \href{mailto:contextualdynamics@gmail.com}{contextualdynamics@gmail.com}.
+  carrying out all required tasks, please complete the checklist and
+  signature page.  You can either (a) fill out the signature page in
+  this PDF, sign it electronically, and email a PDF (of just the
+  signature page) to
+  \href{mailto:contextualdynamics@gmail.com}{contextualdynamics@gmail.com},
+  or (b) use the
+  \href{https://context-lab.com/lab-manual/\#checklist-and-signature-page}{checklist
+    and signature page in the HTML version} of the lab manual.
   \textbf{You are officially a lab member once you have completed all
     tasks in this manual and receipt of your signed and filled-out
     signature page and checklist has been acknowledged by \director.}}
@@ -507,11 +505,11 @@ \chapter{Official lab practices and policies}\label{ch:policy}
   coordination between project team members.
 
 \item At regular intervals, the team reflects on how to become more effective,
-then tunes and adjusts its behavior accordingly. At minimum, all active lab
-members need to reflect on their projects once each week in your \textit{Weekly
-Snippet} (defined below). You should also schedule regular meetings with your
+then tunes and adjusts its behavior accordingly. All active lab
+members are encouraged to reflect on their projects once each week (e.g., via the optional \textit{Weekly
+Snippet}, defined below). You should also schedule regular meetings with your
 project team and/or~\director~(via~\meeting) to discuss progress, goals,
-roadblocks, and project logistics. 
+roadblocks, and project logistics.
 
 \end{enumerate}
 
@@ -786,8 +784,8 @@ \subsection{Authorship guidelines}
   Attendees: all interested lab and non-lab Dartmouth community
   members.
 
-    \item \textbf{Weekly snippets.} Each week, all
-      paid employees must fill out a ``weekly snippet'' 
+    \item \textbf{Weekly snippets.} All lab members are
+      encouraged (but not required) to fill out a ``weekly snippet''
       with brief answers to the following questions:
       \begin{enumerate}
       \item What did you work on over this past week?
@@ -796,19 +794,14 @@ \subsection{Authorship guidelines}
       \item Anything else you'd like to add?
       \end{enumerate}
 
-Reminders to fill out your weekly snippet are automatically sent out (via
-Slack) each Monday at 9 AM. Weekly snippets are required for all paid
-employees and optional for all other lab members. If you are an unpaid
-employee but may request a letter of recommendation, weekly snippets
-help me maintain a sense of what you are working on
-and how you are progressing over time. I'll also refer to
-your snippets during check-in meetings (e.g., to discuss project progress,
+Weekly snippets help \director~maintain a sense of what you are working on
+and how you are progressing over time. They are also referred to
+during check-in meetings (e.g., to discuss project progress,
 contributions, letters of recommendation, annual reviews, etc.).
 Submit your snippet using the ``Fill out your snippet!''
 workflow on Slack, accessible via the Workflows menu in the \texttt{\#general}
 channel (usually near the top left of the window).
-Participants: all paid lab members and any other lab members who want to
-participate. 
+Participants: any lab members who want to participate.
 \end{itemize}
 
 %\newpage
@@ -828,7 +821,7 @@ \subsection{Authorship guidelines}
   an interface for asking questions, storing notes, and sharing
   ideas.  If you have a~\ourschool~NetID you should be able to join the workspace by clicking the link.
   If you do \textit{not} have a NetID, you'll need to \href{https://services.dartmouth.edu/TDClient/1806/Portal/Requests/ServiceDet?ID=30581}{request one here}.
-  \marginnote{\texttt{TASK:} When you join our Slack workspace, initiate our onboarding process using the ``Join the lab!'' workflow.  You can access this workflow in the \texttt{\#general} channel
+  \marginnote{\texttt{TASK:} When you join our Slack workspace, initiate our onboarding process using the \href{https://slack.com/shortcuts/Ft07ESC6CP3J/b1531b6fe100db8522fbd05c6a49ef63}{``Join the lab!'' workflow}.  You can also access this workflow in the \texttt{\#general} channel
   through the Workflows menu (usually near the top left of the window).  Once you initiate the workflow, you'll be guided through the onboarding process.}
 
 \item \href{https://www.github.com}{\textbf{GitHub.}}
@@ -866,6 +859,38 @@ \subsection{Authorship guidelines}
 feel you don't have the appropriate account type, please communicate
 your concerns to \director.
 
+\newthought{Onboarding and offboarding}
+\label{sec:onboarding}
+
+\noindent The lab uses an automated onboarding system to help new members get set up quickly and consistently. When you initiate the ``Join the lab!'' workflow in Slack, you'll be asked to provide:
+\begin{itemize}
+\item Your GitHub username
+\item Your email address (preferably Gmail or Dartmouth)
+\item Your preferred name for the lab website
+\item A short bio (2--3 sentences about yourself and your research interests)
+\item A link to your personal website (optional)
+\end{itemize}
+
+\marginnote{\texttt{NOTE:} After submitting the workflow, please also send a profile photo to \director~via Slack DM. Once approved, your photo and bio will be added to the lab website.}
+
+Once you submit this information, \director~will review your submission and approve your onboarding. The system will then automatically:
+\begin{itemize}
+\item Send you an invitation to the \href{https://github.com/ContextLab}{ContextLab GitHub organization}
+\item Grant you access to the lab's Google Calendars (Contextual Dynamics Lab, Out of lab, and CDL Resources)
+\item Add your profile to the \href{https://contextlab.github.io}{lab website} via a pull request
+\item Update the lab's internal records
+\end{itemize}
+
+You will receive notifications in Slack as each step completes. If any issues arise during the process, \director~will reach out to help resolve them.
+
+\textbf{When leaving the lab,} please notify \director~in advance via Slack to initiate the offboarding process. The offboarding process will:
+\begin{itemize}
+\item Move your profile to the alumni section of the lab website
+\item Revoke access to GitHub repositories and calendars (as appropriate)
+\item Update lab records
+\end{itemize}
+You may be asked to provide your current position and institution URL for the alumni listing.
+
 \newthought{Setting up your development environment}
 \label{sec:dev-environment}
 
@@ -1212,7 +1237,7 @@ \subsection{Authorship guidelines}
   When2Meet is best for selecting a specific time from a
   small number of dates.  \meeting~is used to sign up
   for meeting slots with \director.  You can book a meeting in a free
-  slot through YouCanBook.Me at any time.
+  slot at any time.
 \end{itemize}
 
  \newthought{Attendance policy}
@@ -1557,6 +1582,8 @@ \subsection{Repository of shared lab papers and books}
    you may be required to withdraw your submission and/or cover any
    conference-related expenses that you incurred, at \director's
    discretion.} The preferred methods for creating posters are to use
+ \href{https://github.com/ContextLab/cdl-slides}{cdl-slides} (our
+ custom tool for creating posters from Markdown files),
  \href{https://github.com/deselaers/latex-beamerposter}{LaTeX
    BeamerPoster}, Adobe Illustrator, or
  \href{https://inkscape.org/en/}{Inkscape}.  The lab has several
@@ -1765,6 +1792,14 @@ \chapter{Internal Review Board (IRB) approvals}\label{ch:irb}
     \item \textbf{Network dynamics in human epilepsy (STUDY00029400).}
       Hospital protocol used for studying network dynamics inferred
       via electrocorticographic activity in epilepsy patients.
+    \item \textbf{Decision Making (STUDY00033619).}  Used to study
+      how decisions and moral judgements are impacted by group
+      dynamics.  Behavior only.
+    \item \textbf{Self-Concept and Misperceptions (STUDY00033592).}
+      Study beliefs about the self and others.  Behavior only.
+    \item \textbf{CalmNight Nightmare Monitoring and Intervention
+        Study (STUDY00033484).}  Study and treat nightmares using the
+      FRENZ EEG headband.  Used for at-home sleep studies.
     \item \textbf{Perceptual and Memory Dynamics (STUDY00031514).}
       Used for studies investigating the relationship between
       perceptual and memory metrics and symptoms associated with
@@ -1863,6 +1898,11 @@ \subsection{Current lab members}\label{sec:curr_members}
 \item Andrew Richardson (2025 -- )
 \item Keene Dampal (2025 -- )
 \item Kevin Chang (2025 -- )
+\item Theo Larson (2025 -- )
+\item Jason Kang (2025 -- )
+\item Sam Haskel (2025 -- )
+\item Mak Kelly (2026 -- )
+\item Hye-Sung Kim (2026 -- )
 \end{list}
 \end{multicols}
 
@@ -2005,15 +2045,8 @@ \chapter{Checklist and signature page}
   \item I have created a GitHub account and have been added to the appropriate lab
     GitHub group(s).  If I am unfamiliar with Git, I have gone through
     the GitHub tutorials.
-  \item I am proficient in \LaTeX, allowing me to edit and understand
-  this lab manual's source code.
-\item I have submitted a pull request to the
-  \href{https://github.com/ContextLab/lab-manual}{GitHub repository}
-  that adds my name to the \hyperref[sec:curr_members]{lab members}
-  section, along with any other updates I think would be helpful.  I
-  have also recompiled the PDF of the lab manual by running
-  \texttt{pdflatex} \textbf{twice}, and have ensured that (a) the PDF compiled
-  without errors, and (b) the table of contents was generated correctly.
+  \item I have verified that my name appears in the
+  \hyperref[sec:curr_members]{lab members} section of this manual.
   \item I have run the CDL setup script (described in the
   \hyperref[sec:dev-environment]{Setting up your development environment}
   section) and verified that my development environment is correctly
@@ -2041,7 +2074,7 @@ \chapter{Checklist and signature page}
   \item I agree to regularly attend lab meetings (unless I have a
     course conflict and have informed \director).
     \item I agree to send \director~regular updates regarding my
-      progress and work, including weekly snippets, meetings, Slack
+      progress and work, including meetings, Slack
       discussions, and/or GitHub updates.
       \item If/when I decide to end my affiliation with the lab, I
         will notify \director~and any project members affected by my departure.  I will also coordinate with
@@ -2062,10 +2095,14 @@ \chapter{Checklist and signature page}
   \item I have carefully read through the entire lab manual, and I
     have checked off all of the above items to indicate that I have
     carried out the indicated tasks.
-  \item I will send a digital copy (PDF) of the final two pages of
-    this manual, including checked-off list items, my digital
-    signature, and today's date, to
-    \href{mailto:contextualdynamics@gmail.com}{contextualdynamics@gmail.com}.
+  \item I will complete and sign this checklist by either (a) sending
+    a digital copy (PDF) of the final two pages of this manual,
+    including checked-off list items, my digital signature, and
+    today's date, to
+    \href{mailto:contextualdynamics@gmail.com}{contextualdynamics@gmail.com},
+    or (b) using the
+    \href{https://context-lab.com/lab-manual/\#checklist-and-signature-page}{online
+      checklist and signature page}.
 \end{todolist}
 
 \vspace{0.25in}