# CLAUDE.md

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

## Project Overview

This is the source for commonflow.org, an Astro-based static site that documents
the Git Common-Flow specification. Common-Flow is a git workflow specification
that combines GitHub Flow with versioned releases.

## Build Commands

```bash
# Install tooling (bun) via mise
mise install

# Install dependencies
bun install

# Development server
bun run dev

# Build site (outputs to docs/ directory)
bun run build

# Preview built site
bun run preview

# Type checking
bun run check

# Linting
bun run lint

# Formatting
bun run format
bun run format:check

# Update specs from upstream (fetches from github.com/jimeh/common-flow)
bun run update
```

The site is built to `docs/` for GitHub Pages hosting.

## Architecture

- **Astro 5.x** static site generator
- **Tailwind CSS 4.x** for styling with dark mode support
- **Content Collections** for spec markdown files
- **TypeScript** throughout
- **Bun** as JavaScript runtime and package manager (managed via mise)

### Key Files

- `src/config.ts` - Site configuration with version list
- `src/content.config.ts` - Astro content collection definition
- `src/layouts/BaseLayout.astro` - Base layout with head, meta tags, theme scripts
- `src/layouts/SpecLayout.astro` - Spec page layout composing all sections
- `src/components/` - UI components:
  - `Header.astro` - Site header with navigation
  - `Footer.astro` - Site footer
  - `Hero.astro` - Landing page hero section
  - `AboutSection.astro` - About Common-Flow section
  - `FAQSection.astro` - FAQ section
  - `SectionHeader.astro` - Reusable section header (title + subtitle)
  - `SpecSection.astro` - Spec section with terminology and specification
  - `SpecSidebar.astro` - Spec page table of contents sidebar
  - `TocLink.astro` - Reusable TOC link component
  - `ThemeToggle.astro` - Dark/light mode toggle
  - `VersionSelector.astro` - Spec version dropdown
  - `icons/GitHubIcon.astro` - GitHub SVG icon
- `src/scripts/activeSectionTracker.ts` - Shared scroll-based active section tracking
- `src/pages/index.astro` - Landing page
- `src/pages/404.astro` - 404 error page
- `src/pages/spec/[version].astro` - Dynamic route for spec versions
- `src/utils/parseSpecContent.ts` - Markdown parsing utilities
- `src/content/spec/*.md` - Versioned spec documents
- `public/spec/*.svg` - SVG diagrams for each version
- `scripts/update-specs.ts` - Fetches specs from GitHub

### Updating Spec Versions

1. Add new version to `versions` array in `src/config.ts`
2. Update `currentVersion` if this is the new default
3. Run `bun run update` to fetch specs from GitHub
4. Run `bun run build` to rebuild the site