# AGENTS.md

## Project summary
`ccolors` is a command-line utility that extracts dominant color palettes from images and outputs both terminal-colored swatches and a JSON file containing the extracted colors. It features a single-file design where all functionality is contained in `main.cpp` with no subdirectories, utilizing standard C++17 and the `stb_image.h` header-only library.

## Build/test/lint commands
* **Build requirements**:
  - Compiler: C++17 compliant (g++/clang++)
  - CMake: Version 3.10+
  - CMake configuration:
    ```cmake
    cmake_minimum_required(VERSION 3.10)
    project(ccolors)
    set(CMAKE_CXX_STANDARD 17)
    add_executable(ccolors main.cpp)
    ```
* **Test**: The single-file architecture makes unit testing difficult.
* **Lint / Code style rules**:
  - 4-space indentation
  - No complex macros

## Code style rules
* **Variables**: snake_case (`imagefile`), CamelCase (`Pixel`)
* **Constants**: UPPER_SNAKE_CASE (`argv`, `STB_IMAGE_IMPLEMENTATION`)
* **Functions**: snake_case (`is_jpeg`, `is_png`)
* **Namespaces**: Alias-based (`fs` for `std::filesystem`)
* **Code Structure Patterns**:
  - Early returns for error handling
  - Forward declarations before use
  - Type aliases for commonly used types
  - Defensive programming with comprehensive error checking
  - 4-space indentation, no complex macros

## Directory structure and where things are located
* **Single-file design**: All functionality is contained in `main.cpp` in the root directory. There are no subdirectories.
* **Dependencies**: `stb_image.h` header-only library.

## Constraints agents must adhere to
* **Single-file design**: All core logic, data structures, algorithms, and I/O must remain in `main.cpp` with no separation of concerns.
* **Standard Compatibility**: Must be C++17 compliant.
* **Dependencies**: Keep external dependencies limited to standard library and the included header-only `stb_image.h`.
* **Downsampling & Filtering**: Color extraction must downsample pixels (step = 10) and filter out pixels with brightness < 60 and saturation < 10.
* **Fixed-size Output**: Output must be limited to the top 5 colors.
* **Quantization**: Colors must be quantized into 16×16×16 buckets (4096 keys).
* **Statelessness**: Operation must remain stateless with no persistent storage or global state between runs.