docs: Add Claude AI guidance and improve README

.gitignore

@@ -16,3 +16,4 @@ cache
 vendor
 composer.lock
 *.cache
+.claude

CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+JBZoo Less is a PHP wrapper library for LESS CSS compilation, specifically wrapping [wikimedia/less.php](https://github.com/wikimedia/less.php). It provides a simplified interface with caching, configuration management, and enhanced error handling for compiling LESS files to CSS.
+
+## Development Commands
+
+### Essential Commands
+```bash
+make update      # Install/update all dependencies via Composer
+make test        # Run PHPUnit tests
+make codestyle   # Run all linters and code quality checks
+make test-all    # Run complete test suite (tests + codestyle)
+```
+
+### Testing Commands
+```bash
+vendor/bin/phpunit                                    # Run all tests
+vendor/bin/phpunit tests/DriverGpeasyTest.php        # Run specific driver tests
+vendor/bin/phpunit --filter testCompileSimple        # Run specific test method
+```
+
+The project inherits comprehensive make targets from `jbzoo/codestyle` including individual linting tools like `make test-phpstan`, `make test-psalm`, `make test-phpcsfixer`, etc.
+
+## Architecture Overview
+
+### Core Components
+
+The library consists of 4 main classes in the `JBZoo\Less` namespace:
+
+1. **Less** (`src/Less.php`) - Main public interface
+   - Primary entry point for LESS compilation
+   - Handles configuration validation and preparation
+   - Coordinates between cache and driver systems
+   - Public methods: `compile()`, `setImportPath()`
+
+2. **Gpeasy** (`src/Gpeasy.php`) - Compiler driver
+   - Wrapper around wikimedia/less.php compiler
+   - Handles actual LESS compilation and import path management
+   - Processes custom functions and variables
+
+3. **Cache** (`src/Cache.php`) - File caching system
+   - TTL-based file caching with automatic invalidation
+   - Generates cache file names based on source file paths
+   - Manages cache directory creation and cleanup
+
+4. **Exception** (`src/Exception.php`) - Custom exception handling
+   - Wraps underlying compiler exceptions with enhanced context
+
+### Configuration System
+
+The Less class accepts comprehensive configuration options covering:
+- **Compilation behavior**: force recompilation, debug mode
+- **Path management**: root URL/path, import paths, cache directory
+- **LESS features**: global variables, autoloaded mixins, custom functions
+- **Caching**: cache TTL and directory settings
+
+### Testing Architecture
+
+- **AbstractLessTest** - Base test class with comprehensive test suite
+  - Tests compilation, caching, variables, imports, custom functions
+  - File comparison utilities for validating CSS output
+  - Environment setup (SERVER variables, cache cleanup)
+
+- **DriverGpeasyTest** - Driver-specific test implementation
+  - Inherits all tests from AbstractLessTest
+  - Uses expected output files in `tests/expected-gpeasy/`
+
+Test resources include LESS files, expected CSS outputs, and assets (images) for comprehensive testing scenarios.
+
+## Key Dependencies
+
+- **PHP 8.2+** requirement
+- **wikimedia/less.php** (>=5.4.0) - Core LESS compiler
+- **JBZoo ecosystem**:
+  - `jbzoo/data` - Configuration data handling
+  - `jbzoo/utils` - File system, URL, date utilities
+  - `jbzoo/toolbox-dev` - Development tools and testing framework
+
+## Usage Patterns
+
+### Basic Compilation
+```php
+$less = new Less();
+$cssPath = $less->compile('/path/to/styles.less');
+```
+
+### Advanced Configuration
+```php
+$less = new Less([
+    'cache_path'   => './custom-cache',
+    'global_vars'  => ['primary-color' => '#007bff'],
+    'import_paths' => ['/assets/less/' => '/css/'],
+    'functions'    => ['custom-func' => $callable],
+]);
+```
+
+### Import Path Management
+```php
+$less->setImportPath('/full/path/to/imports/', 'http://site.com/imports/');
+```

README.md

@@ -4,81 +4,152 @@
 [![Stable Version](https://poser.pugx.org/jbzoo/less/version)](https://packagist.org/packages/jbzoo/less/)    [![Total Downloads](https://poser.pugx.org/jbzoo/less/downloads)](https://packagist.org/packages/jbzoo/less/stats)    [![Dependents](https://poser.pugx.org/jbzoo/less/dependents)](https://packagist.org/packages/jbzoo/less/dependents?order_by=downloads)    [![GitHub License](https://img.shields.io/github/license/jbzoo/less)](https://github.com/JBZoo/Less/blob/master/LICENSE)
 
 
-PHP wrapper for [wikimedia/less.php](https://github.com/wikimedia/less.php).
+A powerful PHP wrapper for [wikimedia/less.php](https://github.com/wikimedia/less.php) that provides enhanced LESS compilation with caching, advanced configuration options, and streamlined error handling.
 
+## Features
 
-## Install
-```sh
+- **Smart Caching**: Automatic file-based caching with TTL support
+- **Flexible Configuration**: Comprehensive options for paths, variables, and compilation behavior
+- **Global Variables**: Define LESS variables available across all compiled files
+- **Auto-loading**: Automatically include mixin files before compilation
+- **Custom Functions**: Register custom PHP functions for use in LESS files
+- **Import Path Management**: Configure multiple import directories with URL mappings
+- **Enhanced Error Handling**: Detailed error messages with context
+
+
+## Requirements
+
+- PHP 8.2 or higher
+- Composer
+
+## Installation
+
+```bash
 composer require jbzoo/less
 ```
 
-## Usage
+## Quick Start
+
 ```php
 use JBZoo\Less\Less;
 
-try { // Any error handling
+// Basic usage
+$less = new Less();
+$cssPath = $less->compile('/path/to/styles.less');
 
-    // There is not option required
-    $less = new Less([
-        'force'        => false,                    // Can forced compile on each compile() calling
-        'debug'        => false,                    // On/Off Source map for browser debug console
+// With custom cache directory
+$less = new Less(['cache_path' => './custom-cache']);
+$cssPath = $less->compile('./assets/styles.less');
+```
+
+## Advanced Configuration
 
-        'root_url'     => 'http://site.com/',       // Root URL for all CSS files and debug mode
-                                                    // For example - background:url('http://site.com/image.png')
+All configuration options are optional and can be customized based on your needs:
 
-        'root_path'    => '/full/path/to/site',     // Full path to root of web directory
+```php
+use JBZoo\Less\Less;
 
-        'global_vars'  => [                         // Some vars that will be in all less files
-            'color'  => '#f00',                     // @color: #f00;
-            'media' => 'print',                     // @media: print;
+try {
+    $less = new Less([
+        // Compilation behavior
+        'force'        => false,                    // Force recompilation on each call
+        'debug'        => false,                    // Enable source maps (future feature)
+
+        // Path configuration
+        'root_url'     => 'http://site.com/',       // Root URL for CSS asset references
+        'root_path'    => '/full/path/to/site',     // Full path to web root directory
+
+        // LESS features
+        'global_vars'  => [                         // Global variables available in all files
+            'primary-color' => '#007bff',           // Becomes @primary-color: #007bff;
+            'font-size'     => '14px',              // Becomes @font-size: 14px;
         ],
 
-        'autoload'     => [                         // Autoload before eash compiling
-            '/full/path/to/my_mixins.less',         // See the best of collection here
-        ],                                          // https://github.com/JBZoo/JBlank/tree/master/less/misc
+        'autoload'     => [                         // Files automatically included before compilation
+            '/full/path/to/mixins.less',
+            '/full/path/to/variables.less',
+        ],
 
-        'import_paths' => [                         // Import paths
+        'import_paths' => [                         // Directory mappings for @import statements
             '/full/path/to/assets/less/' => 'http://site.com/assets/less/',
-            './or/relative/path/to/dir/' => './or/relative/path/to/dir/',
+            './relative/path/to/less/'   => './relative/path/to/less/',
         ],
 
-        'cache_path'   => './cache',                // Where JBZoo/Less will save compiled CSS-files
-        'cache_ttl'    => 2592000,                  // How often rebuild css files (in seconds)
+        // Caching configuration
+        'cache_path'   => './cache',                // Cache directory location
+        'cache_ttl'    => 2592000,                  // Cache TTL in seconds (30 days)
 
-        'functions' => [                            // Custom functions for less (only for gpeasy!)
-            'str-revert' => function ($arg) {       // Register name `str-revert()`
-                $arg->value = strrev($arg->value);  // Just revert argument
-                return $arg;                        // Result: str-revert('1234567890'); => '0987654321';
+        // Custom functions (advanced feature)
+        'functions' => [
+            'str-reverse' => function ($arg) {
+                $arg->value = strrev($arg->value);
+                return $arg;
             },
         ],
     ]);
 
+    // Add import paths dynamically
     $less->setImportPath(
-        '/full/path/to/other/import/directory/',    // Full or relative path
-        'http://site.com/other/import/directory/'   // Not required
+        '/additional/import/directory/',
+        'http://site.com/additional/directory/'     // URL mapping (optional)
     );
 
-    $fullCSSpath_1 = $less->compile('/full/path/to/styles.less');       // Basepath from config
-    $fullCSSpath_2 = $less->compile('./relative/path/to/styles.less');  // OR relative path
-    $fullCSSpath_3 = $less->compile(
+    // Compile LESS files
+    $cssPath1 = $less->compile('/full/path/to/styles.less');
+    $cssPath2 = $less->compile('./relative/path/to/styles.less');
+    $cssPath3 = $less->compile(
         './relative/path/to/styles.less',
-        'http://site.com/relative/path/to/'                             // Force base path for any URLs
+        'http://site.com/custom/base/path/'         // Override base path for URLs
     );
 
 } catch (JBZoo\Less\Exception $e) {
-    echo 'JBZoo/Less: ' . $e->getMessage();
+    echo 'Compilation error: ' . $e->getMessage();
 }
-
 ```
 
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `force` | bool | `false` | Force recompilation on every call, ignoring cache |
+| `debug` | bool | `false` | Enable debug mode (future: source maps) |
+| `root_url` | string | auto-detected | Base URL for asset references in CSS |
+| `root_path` | string | auto-detected | Full filesystem path to web root |
+| `global_vars` | array | `[]` | Global LESS variables available in all files |
+| `autoload` | array | `[]` | LESS files to automatically include before compilation |
+| `import_paths` | array | `[]` | Directory mappings for @import resolution |
+| `cache_path` | string | `'./cache'` | Directory for storing compiled CSS files |
+| `cache_ttl` | int | `2592000` | Cache time-to-live in seconds (30 days) |
+| `functions` | array | `[]` | Custom PHP functions callable from LESS |
+
+
+## Development
 
-## Unit tests and check code style
-```sh
+### Running Tests
+
+```bash
+# Install dependencies
 make update
+
+# Run all tests and code quality checks
 make test-all
+
+# Run only PHPUnit tests
+make test
+
+# Run only code style checks
+make codestyle
 ```
 
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests and ensure code quality (`make test-all`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) file for details.