# Repository Guidelines

## Project Structure & Module Organization
- `src/`: YAML "DNA" sources for the two schemes (`neon.yaml`, `aeon.yaml`).
- `templates/<app>/`: Jinja2 templates (`*.j2`) and optional `meta.yaml` that defines per-app output strategy.
- `dist/`: Generated theme outputs for each app; treat as build artifacts and do not edit by hand.
- `build.py`: Python build engine that renders templates into `dist/`.
- Docs and specs: `README.md`, `GEMINI.md`, `apex-neon.md`, `apex-aeon.md`.
- Assets: palette PNGs at repo root.

## Build, Test, and Development Commands
- `uv run build.py` regenerates all themes from `src/` into `dist/` (requires Python 3.12+ and deps in `pyproject.toml`).
- There is no dev server or watch mode; rerun the build after updating YAML or templates.

## Coding Style & Naming Conventions
- Python code follows 4-space indentation and `snake_case` for functions/variables.
- Template outputs follow the naming pattern `apex-<scheme>.<ext>` for per-scheme builds.
- Aggregated outputs (when `meta.yaml` sets `strategy: aggregated`) keep the template base name (e.g., `apex.json`, `gtk.css`).
- Keep YAML keys consistent with existing `src/*.yaml` semantics; add new roles only if they are truly required.

## Testing Guidelines
- No automated tests are currently defined.
- Validate changes by running `uv run build.py` and checking the generated files in `dist/` for both Neon and Aeon outputs.

## Commit & Pull Request Guidelines
- Commit messages follow Conventional Commits as seen in history: `feat:`, `docs:`, `chore:`, `refactor:`.
- Keep changes scoped to one intent; prefer small, reviewable commits.
- PRs should include a short summary, list of affected templates/apps, and the command used to build (`uv run build.py`).
- For visual/theme changes, include a brief before/after note or screenshots when possible.

## Theme Rules & Source of Truth
- `GEMINI.md` is the authoritative source for color semantics and rules; update `src/*.yaml` first, then templates if needed.
- Avoid introducing ad-hoc colors that violate the semantic palette.