# AGENTS.md

Guidance for AI coding agents working in this repository.

## Project overview

This repo collects terminal color schemes and generates them for 30+ targets (iTerm2, Alacritty, Kitty, WezTerm, VS Code, Windows Terminal, etc.). Source themes live in `yaml/` (`.yml`, preferred for new themes) and `schemes/` (`.itermcolors`, for themes exported directly from iTerm2). Everything else under format directories (`alacritty/`, `kitty/`, `wezterm/`, …) is generated output.

## Repository layout

| Path | Purpose |
|------|---------|
| `yaml/` | Preferred source for new themes (Gogh-based YAML format) |
| `schemes/` | iTerm2 `.itermcolors` source files (use when exporting from iTerm2) |
| `tools/` | Generation scripts, converters, and Jinja2 templates |
| `tools/templates/` | Per-format Jinja2 templates |
| `screenshots/` | Auto-generated theme preview images |

## Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Python version: see `.python-version` (currently 3.10). Docker alternative: `./generate-all.sh`.

Activate the venv before running commands below (`source .venv/bin/activate`), or prefix with `.venv/bin/python`.

## Common commands

```bash
# Generate all themes for all formats
cd tools && python gen.py

# Generate one theme (preferred while iterating)
cd tools && python gen.py -s "Your Theme Name"

# Generate one format template only
cd tools && python gen.py -t kitty

# Full local pipeline (macOS; regenerates all themes, Terminal profiles, screenshots, README)
./generate-all-nodocker.sh

# Check WCAG contrast (default threshold 1.75, matches gen.py)
python tools/wcag_check.py -s "Your Theme Name"
python tools/wcag_check.py --schemes-dir schemes   # all schemes

# YAML themes: generate .itermcolors first, then check
cd tools && python gen.py -s "Your Theme Name"
python tools/wcag_check.py -s "Your Theme Name"

# Check that every theme has a licenses.yml entry
python tools/check_licenses.py

# Generate only themes with a known open licence, into a separate directory
cd tools && python gen.py --redistributable -o /path/to/output

# Visual preview (display-only truecolor; does not change terminal palette)
python tools/preview_theme.py -s "Your Theme Name"
```

## Adding a new theme

**Prefer YAML** unless the theme is being exported directly from iTerm2.

### YAML (default)

1. Create `yaml/Your Theme Name.yml` following `yaml/README.md`. Use the display name as the filename — spaces are fine; do not slugify or use underscores.
2. Convert from other formats if needed: `tools/kitty_to_yaml.py`, `tools/ghostty_to_yaml.py`.
3. Regenerate with `cd tools && python gen.py -s "Your Theme Name"`.

### iTerm2 export (when applicable)

1. Export from iTerm2 and add `schemes/Your Theme Name.itermcolors`.
2. Regenerate with `cd tools && python gen.py -s "Your Theme Name"`.

For both paths: add the theme's entry to `licenses.yml` (SPDX identifier, `unknown` or `nonfree`, plus a source URL) and run `python tools/check_licenses.py`. Optionally update `CREDITS.md`. Do **not** hand-edit files in generated format directories. See `README.md` (Contribute) for full details.

## Adding a new output format

1. Create a Jinja2 template in `tools/templates/` using placeholders documented in `README.md` (Contribute → How to add new template).
2. Test with `cd tools && python gen.py -t <template-name>`.
3. Update `requirements.txt` or `.python-version` only if dependencies change.

## Important rules

- **Prefer YAML for new themes.** Add `yaml/*.yml` unless the source is a direct iTerm2 export.
- **Edit sources, not outputs.** Change `yaml/` or `schemes/`, then regenerate. Never manually patch hundreds of generated theme files.
- **Use selective generation** (`-s`, `-t`) when working on a single theme or format to avoid long runtimes.
- **Theme naming.** Name source files as the display name (`yaml/Catppuccin Mocha.yml`, `schemes/SpaceGray Eighties.itermcolors`). No slugifying or underscores. YAML `name:` must match the filename if set. Quote names with spaces in CLI commands.
- **Avoid unrelated changes.** This repo is large; keep diffs focused on the task (one theme, one template, one tool fix).
- **README screenshots** are auto-generated by `tools/generate_screenshots_readme.py`; do not hand-edit the screenshots section in `README.md`.
- **Disclose agent usage.** Note AI agent involvement in commit messages and PR descriptions. Agent-generated code and themes are welcome; the user may remove the disclosure if they prefer.

## CI behavior

GitHub Actions (`.github/workflows/generate-all.yml`) regenerates themes and screenshots on pushes to `master` that touch `schemes/`, `yaml/`, or `screenshots/README.md`. PRs should include source changes; generated artifacts may be updated by CI.

## Further reading

- `README.md` — installation, contribution workflow, and template placeholder reference
- `yaml/README.md` — YAML source format
- `CREDITS.md` — theme attribution