Guidance for AI coding agents working in this repo. For human onboarding see
CONTRIBUTING.md, which this file does not repeat.
The public website for the Thoughtful AI Tools Lab (https://thoughtful-ai.com),
built with Astro 5 + React + Tailwind, deployed on Cloudflare. The lab's actual
research application is a different repo (AIToolsLab/writing-tools) — do not
look for app/model code here.
npm install, thennpm run buildmust pass. CI (.github/workflows/ci.yml) runs the build on every PR. Always runnpm run buildbefore claiming a change works — there is no test suite, so a clean build is the bar.
- Content is data-driven; prefer editing data over markup. People are
per-person JSON files in
src/data/people/; publications are an array insrc/pages/publications.astro. When adding similar content, follow the existing data pattern instead of hand-writing new markup blocks. - The page shell, SEO tags, and canonical URL live in
src/layouts/Layout.astro. The canonical URL is derived from the request path — don't hardcode it. - The header is a React island (it has a mobile-nav toggle) hydrated with
client:loadso it appears in static HTML — don't switch it back toclient:only. The footer is a static.astrocomponent (no interactivity, no hydration); keep static UI static rather than making it a React island. - Match surrounding Tailwind utility classes; avoid introducing bespoke CSS.
README orients a visitor ("what is this"), CONTRIBUTING.md onboards a human
contributor ("how to set up and where things live"), and CLAUDE.md is read
automatically by coding agents as standing instructions — so it focuses on the
constraints and verification steps an agent needs to not break things, and stays
short to keep the agent's context lean.