# CLAUDE.md

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

## Build & Development Commands

```bash
# Install for development (using uv)
uv sync --extra dev

# Install with Google API support
uv sync --extra dev --extra google

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ -v --cov=src/gravitas_md2gdocs

# Run a single test
uv run pytest tests/test_converter.py::TestMarkdownParser::test_parse_header -v

# Lint and format
uv run ruff check .
uv run ruff format .

# Check formatting only
uv run ruff format --check .

# Build package
uv build
```

## Architecture

This library converts Markdown to Google Docs API batchUpdate requests.

**Core flow:**
1. `MarkdownParser` (parser.py) parses markdown text into a list of `Paragraph` objects, each containing `TextRun` objects with styling info
2. `DocsRequestBuilder` (converter.py) converts those paragraphs into Google Docs API request dictionaries
3. `to_requests()` in `__init__.py` is the main entry point that chains these together

**Key classes:**
- `TextRun`: Dataclass holding text with inline styling (bold, italic, code, link, etc.)
- `Paragraph`: Dataclass holding runs plus paragraph-level info (heading level, list type, blockquote)
- `MarkdownParser`: Regex-based parser that produces Paragraph lists
- `DocsRequestBuilder`: Generates insertText, updateTextStyle, updateParagraphStyle, and createParagraphBullets requests

**Google API helpers** (require `gravitas-md2gdocs[google]`): `append()`, `replace()`, `insert_at()`, `replace_range()` wrap the docs service to provide common operations.

**Important implementation detail:** The builder reverses the request list because Google Docs API applies requests in order and inserting at an index shifts subsequent content.
