# CLAUDE.md

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

## Build

```bash
uv run build.py
```

Regenerates all theme files from `src/*.yaml` via Jinja2 templates into `dist/`. There is no watch mode — rerun after any YAML or template change. Python 3.12+ required; dependencies managed via `uv` (`pyproject.toml`).

## Architecture

Apex is a **theme factory** — a build system that generates native theme configs for 18 applications from a single semantic color specification.

**Data flow:**
1. `src/neon.yaml` and `src/aeon.yaml` define the canonical color palette and semantic roles
2. `templates/<app>/*.j2` define per-application output formats (Lua, JSON, TOML, CSS, Conf, etc.)
3. `templates/<app>/meta.yaml` controls the build strategy:
   - `strategy: individual` → outputs `apex-neon.<ext>` and `apex-aeon.<ext>` separately
   - `strategy: aggregated` → outputs a single file containing both schemes (e.g., `apex.json` for Zed)
4. `build.py` orchestrates rendering; `dist/` holds all generated artifacts (gitignored)

**Adding a new app target:** create `templates/<app>/`, add a `meta.yaml` with strategy, write `.j2` templates using the YAML variables, then run the build.

## Theme Design Rules

`GEMINI.md` is the authoritative source of truth for color semantics. Key axioms:

- **Red (`#ff0044`) = Active Intent** — cursor, current location, selection, critical errors. Text on red backgrounds must be `#050505` (Neon) or `#0a0a0a` (Aeon).
- **Cyan = Informational** — never use for errors or destruction.
- **Purple = Sacred** — reserved for root access and exceptional system states.
- **Bright ANSI variants (8–15)** are for escalated/active states only.
- Do not introduce colors without a semantic reason. If it has no signal purpose, remove it.

Before modifying `src/*.yaml`, consult `GEMINI.md` to verify that any new or changed role fits the semantic palette.

## Conventions

- Commit style: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`)
- Template output names: `apex-<scheme>.<ext>` for individual; base name for aggregated
- YAML keys in `src/`: keep consistent with existing semantic roles; add new roles only when truly necessary
- `dist/` is build output — never edit by hand

## Validation

After changes, run `uv run build.py` and inspect relevant files in `dist/`. For Neovim-specific validation, `scripts/nvim-audit.sh` is available.

## Scripts

- `scripts/release.sh` — Per-app versioning and Gitea release automation. Usage: `bash scripts/release.sh <semver>`. Discovers changed apps via git diff, updates `meta.yaml` version fields, builds, and publishes tarballs. Supports `--dry-run`.
- `scripts/nvim-audit.sh` — Validates the built Neovim theme by running headless Neovim. Requires `dist/nvim/colors/apex-neon.lua` to exist first.