1 files changed, 152 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c40c913
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,152 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+NeBuild is a minimal build system that uses manifest files (JSON or TOML) to define build configurations. It's a C++20 project that compiles C++ projects based on declarative manifest files, supporting both POSIX and Windows platforms.
+
+## Build Commands
+
+### Using Make (Primary)
+```bash
+# Build NeBuild for POSIX systems (uses clang++)
+make build-nebuild
+
+# Build NeBuild for Windows (cross-compile with MinGW)
+make build-nebuild-windows
+
+# Show available make targets
+make help
+```
+
+### Using CMake (Alternative)
+```bash
+# Configure and build
+cmake -S . -B build
+cmake --build build
+
+# Or use the custom target
+cmake --build build --target build-nebuild
+```
+
+### Using NeBuild (Self-hosting)
+```bash
+# Build a project using a manifest file
+./nebuild path/to/manifest.json
+./nebuild path/to/manifest.toml
+
+# Dry-run mode (don't execute build)
+./nebuild -dry-run manifest.json
+./nebuild -n manifest.json
+
+# Check build system name
+./nebuild manifest.json -build-system
+
+# Show version
+./nebuild -v
+```
+
+## Architecture
+
+### Core Components
+
+**Manifest Builders** (`src/lib/`, `include/NeBuildKit/`)
+- `IManifestBuilder`: Abstract base class defining the builder interface
+- `JSONManifestBuilder`: Parses `.json` manifest files using nlohmann/json
+- `TOMLManifestBuilder`: Parses `.toml` manifest files using toml++
+- Each builder implements `BuildTarget(BuildConfig&)` and `BuildSystem()`
+
+**CLI** (`src/cli/main.cc`)
+- Entry point that routes manifest files to appropriate builder based on file extension
+- Supports multi-threaded builds (each manifest file processed in a thread)
+- Handles command-line flags: `-v`, `-dry-run`, `-n`, `-h`, `-build-system`
+
+**Configuration** (`include/NeBuildKit/Detail/Config.h`)
+- `BuildConfig`: Holds build state (path, failure status, dry-run mode)
+- `Logger::info()`: Custom logging with colored output via rang library
+- Version constants: `NEBUILD_VERSION`, `NEBUILD_VERSION_BCD`
+
+### Manifest File Format
+
+Both JSON and TOML manifests support the same fields:
+- `compiler_path`: Path to compiler executable (e.g., "clang++")
+- `compiler_std`: C++ standard (e.g., "c++20")
+- `compiler_headers_path`: Additional header search paths (optional)
+- `headers_path`: Header include directories
+- `sources_path`: Source files to compile
+- `output_name`: Output executable/library path
+- `compiler_flags`: Additional compiler flags
+- `cpp_macros`: Preprocessor macros to define
+- `run_after_build`: Whether to run the output after building
+
+See `example/` directory for reference manifests.
+
+### Dependencies (vendor/)
+
+- **nlohmann/json**: JSON parsing library
+- **toml++**: TOML parsing library
+- **rang**: Terminal color output library
+
+All dependencies are vendored and included via `-I./vendor` flag.
+
+## Code Structure
+
+```
+src/
+├── cli/          # Command-line interface
+│   └── main.cc   # Main entry point
+└── lib/          # Core build logic
+    ├── IManifestBuilder.cc
+    ├── JSONManifestBuilder.cc
+    └── TOMLManifestBuilder.cc
+
+include/NeBuildKit/
+├── Detail/
+│   └── Config.h              # BuildConfig, Logger, version info
+├── IManifestBuilder.h        # Base interface
+├── JSONManifestBuilder.h     # JSON builder
+└── TOMLManifestBuilder.h     # TOML builder
+```
+
+## Development Notes
+
+### Compiler Requirements
+- Requires C++20 support
+- Default compiler: `clang++` (can be overridden in Makefile)
+- CMake minimum version: 3.30
+
+### File Extension Routing
+The CLI automatically selects the builder based on file extension:
+- `.json` → `JSONManifestBuilder`
+- `.toml` → `TOMLManifestBuilder`
+- Other extensions → Error
+
+### Build Process Flow
+1. CLI parses command-line arguments
+2. For each manifest file, spawn a thread
+3. Create appropriate builder based on file extension
+4. Builder parses manifest and constructs compiler command
+5. Execute compiler via `std::system()`
+6. Optionally run output if `run_after_build` is true
+7. Join thread and check `BuildConfig` for failures
+
+### Working with Builders
+
+When modifying or adding builders:
+- Inherit from `IManifestBuilder` using the `NEBUILD_MANIFEST_BUILDER` macro
+- Implement `BuildTarget(BuildConfig&)` to parse manifest and execute build
+- Implement `BuildSystem()` to return a descriptive name
+- Use `NeBuild::Logger::info()` for all output (not `std::cout`)
+- Set `config.has_failed_` on errors
+- Check `config.dry_run_` before executing system commands
+
+### Branches
+- `develop`: Main development branch (default, CI enabled)
+- Other feature branches for specific work
+
+## CI/CD
+
+GitHub Actions runs on the `develop` branch:
+- Runs on Ubuntu with `build-essential`
+- Builds using `make build-nebuild`