everforest-resources/CLAUDE.md

# CLAUDE.md

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

## Project Overview

This is the **everforest-resources** repository - an unofficial hub for Everforest color scheme resources. The project follows a **generator-first** approach where all theme files, configurations, and outputs are generated from canonical palette definitions.

**Critical Rule**: LLM AGENTS SHALL NOT DEVIATE FROM THE THEME SPEC. All changes must strictly follow the specification in AGENTS.md.

## Architecture

### Core Philosophy

- **Generator-first**: All outputs derive from `palettes/everforest.(json|yaml)`
- **Template system**: CLI tools use `template.txt` files with color placeholders (e.g., `{{bg}}`, `{{fg}}`, `{{red}}`) that are replaced by the generator
- **No manual edits**: Generated artifacts MUST NOT be hand-edited
- **ANSI-only for CLI**: CLI tools use ANSI-16 SGR codes only, never raw hex
- **Hex for GUI**: GUI/editor themes may use hex values but only from generator output

### Repository Structure

- `palettes/`: Canonical Everforest palette definitions (JSON/YAML)
- `scripts/`: Generator scripts (Node.js .mjs modules)
- `terminals/`: Terminal configs (WezTerm, Alacritty, Kitty, Windows Terminal, Ghostty)
- `web/`: CSS variables and demo with Playwright snapshots
- `cli/`: CLI tool configs (LS_COLORS, dircolors, eza, ripgrep, fzf, delta, bat, htop, starship, zsh, fish, tmux, btop, bottom, glances, neofetch, ranger, lf, mc, lazygit, gitui, tig, fd, jq, less, zoxide, atuin)
- `editors/`: Editor themes (Neovim minimal Lua, VS Code, JetBrains unified, Zed, Sublime Text)
- `docs/`: Documentation (CLI.md)
- `verify/`: Container verifier
- `.github/`: Workflows and CODEOWNERS

### Theme Variants

- Six variants total: dark/light × hard/medium/soft
  - If variant missing, fallback to medium
  - All variants MUST be present for terminals, CLI tools, editors, web

## Development Commands

Core development commands for the project:

    npm run lint        # Check code with Biome linter
    npm run lint:fix    # Auto-fix linting issues with Biome
    npm run format      # Format code with Biome
    npm run generate    # Generate all theme files from palettes
    npm run validate    # Validate generated outputs
    npm run ci          # Run full CI suite (lint + generate + validate + snapshots)
    npm run snapshots   # Generate Playwright snapshots
    make generate       # Alternative to npm run generate
    make validate       # Alternative to npm run validate
    make ci             # Alternative to npm run ci
    make install-lscolors  # Copy LS_COLORS snippet
    make demo           # Run web demo server
    make snapshots      # Run Playwright snapshots

## Installation and Verification

    ./install.sh cli                      # Deploy CLI configs to ~/.config
    ENGINE=docker ./verify/verify.sh      # Verify in container

## Implementation Guidelines

### Editing Rules

1. **Only edit palette and template files**: Changes should only be made to `palettes/everforest.(json|yaml)` and `template.txt` files
2. **Template placeholders**: Use `{{bg}}`, `{{fg}}`, `{{red}}`, `{{orange}}`, `{{yellow}}`, `{{green}}`, `{{aqua}}`, `{{blue}}`, `{{purple}}`, `{{gray1}}`, `{{gray2}}`, `{{gray3}}`
3. **Never hand-edit outputs**: All generated files are regenerated automatically
4. **Run generator after changes**: Always regenerate after palette or template modifications
5. **Commit all sources**: Include palette, template, and generated files in commits

### Code Quality

- **Biome linting**: All JavaScript code must pass Biome linting and formatting
- **Auto-formatting**: Use `npm run format` to ensure consistent code style
- **No raw hex in CLI configs**: Use ANSI color names/codes only
- **Use indented code blocks**: Never use triple backticks in documentation
- **Follow conventional commits**: All commits must follow conventional commit format
- **Pre-commit validation**: Pre-commit hooks prevent raw hex and enforce regeneration

### Generator Architecture

The main generator (`scripts/generate-themes.mjs`) implements:

- Palette loader for JSON/YAML
- Template processor: reads `template.txt` files and replaces placeholders with palette values
- Writers for each target (terminals, CLI tools, editors, web)
- Variant generation (all 6 variants where applicable)
- ANSI mapping for CLI tools
- Hex output for GUI applications

### CLI Tool Specifications

- **LS_COLORS**: Archives→bold yellow, images→purple, docs→blue
- **ripgrep**: ripgreprc with ANSI mappings
- **fzf**: FZF_DEFAULT_OPTS with Everforest accents
- **delta**: git-delta config with ANSI mapping
- **bat**: Minimal config forwarding to terminal theme
- **htop**: htoprc with color_scheme=0
- **starship**: starship.toml with accent mappings
- **fish**: Color schemes + minimal prompt + Tide preset
- **tmux**: everforest.tmux.conf with ANSI mappings
- **btop**: Modern htop alternative with extensive color customization
- **bottom**: Cross-platform system monitor (Rust) with color themes
- **glances**: System monitoring tool with color themes
- **neofetch**: System information display with color support
- **ranger**: Terminal file manager with color scheme support
- **lf**: Lightweight file manager (ranger alternative)
- **mc**: Midnight Commander with theme support
- **lazygit**: Terminal UI for git with theme support
- **gitui**: Terminal UI for git with color customization
- **tig**: Text-mode git interface with color customization
- **fd**: Find alternative with color output
- **jq**: JSON processor with syntax highlighting
- **less**: Pager with color support via LESS_TERMCAP
- **zoxide**: Smart cd command with prompt integration
- **atuin**: Shell history with TUI theming

## CI/CD Pipeline

Required checks (all must pass for merge):

- **lint**: Biome linting and formatting checks
- **build**: Generator + validation
- **snapshots**: Playwright demo renders
- **commitlint**: Conventional Commits enforcement
- **cli-verify**: Install + verify generated configs

## Contributing Workflow

1. Edit only `palettes/everforest.(json|yaml)` and `template.txt` files
2. Use template placeholders: `{{bg}}`, `{{fg}}`, `{{red}}`, `{{orange}}`, `{{yellow}}`, `{{green}}`, `{{aqua}}`, `{{blue}}`, `{{purple}}`, `{{gray1}}`, `{{gray2}}`, `{{gray3}}`
3. Lint and format code: `npm run lint:fix && npm run format`
4. Run `npm run generate` (when implemented)
5. Commit palette + template + generated files
6. Ensure all CI checks pass
7. Follow conventional commit format

## Documentation Rules

- **Indented code blocks only**: Never use triple backticks (```)
- **Examples use 4-space indentation**
- **Generator-derived content**: Don't document what can be discovered from files
- **Focus on architecture**: Document high-level patterns requiring multiple files to understand

## Current Status

The repository is in initial development phase:
- ✅ Palette definitions created
- ✅ Comprehensive specification written
- ⏳ Generator implementation pending
- ⏳ File structure creation pending
- ⏳ CI/CD setup pending

Follow the implementation steps in `meta/implementation-steps.md` for systematic development.