docs: Enhance project documentation and add Claude guide (#40)

- Introduce CLAUDE.md to provide detailed context and instructions for
AI assistants like Claude Code.
- Revamp README.md for better clarity and comprehensiveness.
- Add new sections to README.md, including Features, Advanced Usage,
Requirements, Architecture, and Development.
- Improve existing sections like Installation and Basic Usage.
- Update .gitignore to exclude .claude files.

Author: SmetDenis

.gitignore

@@ -16,3 +16,4 @@ build
 vendor
 phpunit.xml
 *.cache
+.claude

CLAUDE.md

@@ -0,0 +1,144 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+JBZoo Composer-Diff is a PHP CLI tool that compares two versions of composer.lock files and shows what packages have changed. It's particularly useful for visualizing dependency changes after running `composer update`, providing detailed output in console, markdown, or JSON formats with links to compare views on package repositories.
+
+## Core Architecture
+
+### Command-Line Interface
+- Built on **Symfony Console** and **JBZoo CLI** framework
+- Single command application with `DiffAction` as the main command (`src/Commands/DiffAction.php`)
+- Executable binary: `composer-diff` (defined in composer.json bin section)
+- Entry point through the binary file `/composer-diff`
+
+### Core Classes
+- **`Diff`** (`src/Diff.php`) - Main comparison logic with version change detection (New, Removed, Changed, Upgraded, Downgraded)
+- **`Comparator`** (`src/Comparator.php`) - Orchestrates the comparison process between composer.lock files
+- **`ComposerLock`** (`src/ComposerLock.php`) - Parses and extracts package data from composer.lock files
+- **`Package`** (`src/Package.php`) - Represents individual package with version and URL information
+- **`Url`** (`src/Url.php`) - Generates comparison URLs for different Git hosting platforms
+
+### Output Renderers (`src/Renders/`)
+- **`Console`** - Default colored table output for terminal
+- **`Markdown`** - Generates markdown tables for PRs/documentation
+- **`JsonOutput`** - Machine-readable JSON format
+- **`AbstractRender`** - Base class for all output formats
+
+## Common Commands
+
+### Development Setup
+```bash
+make build           # Install dependencies and build phar
+make update          # Install/update dependencies and build phar
+```
+
+### Testing
+```bash
+make test            # Run PHPUnit tests
+make test-all        # Run all tests and code quality checks
+make test-drupal     # Test with real Drupal upgrade scenario
+make test-manual     # Run manual test examples with sample data
+```
+
+### Code Quality (via JBZoo Toolbox)
+```bash
+make codestyle       # Run all linters and code style checks
+```
+
+### Build Process
+```bash
+make build-phar      # Build composer-diff.phar executable
+make create-symlink  # Create symlink vendor/bin/composer-diff → build/composer-diff.phar
+```
+
+### Usage Examples
+```bash
+# Basic usage (compares HEAD:composer.lock with ./composer.lock)
+php ./vendor/bin/composer-diff
+
+# Compare specific files
+php ./composer-diff --source="old/composer.lock" --target="new/composer.lock"
+
+# Different output formats
+php ./composer-diff --output=markdown
+php ./composer-diff --output=json
+
+# Filter environments
+php ./composer-diff --env=require      # Production dependencies only
+php ./composer-diff --env=require-dev  # Development dependencies only
+```
+
+## Package Detection Logic
+
+The tool identifies changes by:
+1. **Version Comparison**: Uses Composer's semantic versioning via `composer/semver`
+2. **Hash Detection**: Recognizes dev packages with commit hashes (40-character strings without dots)
+3. **URL Generation**: Creates compare links for GitHub, GitLab, and Bitbucket repositories
+4. **Change Classification**: Categorizes as New, Removed, Upgraded, Downgraded, Changed, or Same
+
+## Testing Strategy
+
+### Test Structure
+- **Unit Tests**: `tests/` directory with comprehensive coverage of all classes
+- **Fixture Data**: `tests/fixtures/` contains realistic composer.lock samples for various scenarios
+- **Integration Tests**: Real-world examples like Drupal version comparisons
+- **Manual Testing**: Built-in examples in Makefile for output verification
+
+### Test Scenarios Covered
+- New package installation
+- Package removal
+- Version upgrades/downgrades
+- Dev branch changes (hash-based versions)
+- Complex dependency matrices
+- Different environment filtering (require vs require-dev)
+
+## Build System
+
+### JBZoo Toolbox Integration
+Uses JBZoo's standardized development toolchain:
+- Inherits comprehensive Makefile targets from `vendor/jbzoo/codestyle/src/init.Makefile`
+- Automated code style, static analysis, and testing via `jbzoo/toolbox-dev`
+- Consistent development experience across JBZoo ecosystem
+
+### PHAR Distribution
+- Builds standalone `build/composer-diff.phar` executable
+- Supports global installation via `composer global require jbzoo/composer-diff`
+- GitHub releases provide downloadable phar files
+
+## Dependencies
+
+### Production
+- `php: ^8.2` with `ext-json` and `ext-filter`
+- `jbzoo/cli: ^7.2.4` - Enhanced Symfony Console wrapper
+- `jbzoo/data: ^7.2` - Data manipulation utilities
+- `jbzoo/markdown: ^7.0.2` - Markdown generation
+- `symfony/console: >=6.4`, `symfony/process: >=6.4`
+- `composer/semver: >=1.0` - Version comparison logic
+
+### Development
+- `jbzoo/toolbox-dev: ^7.3` - Complete development toolchain
+- `composer/composer: >=2.0` - For testing with real composer.lock files
+
+## File Structure Patterns
+
+```
+src/
+├── Commands/DiffAction.php    # Main CLI command
+├── Renders/                   # Output format implementations
+├── Diff.php                   # Core comparison logic
+├── Comparator.php            # Comparison orchestration
+├── ComposerLock.php          # Lock file parsing
+├── Package.php               # Package representation
+├── Url.php                   # URL generation
+└── Exception.php             # Custom exceptions
+
+tests/
+├── fixtures/                 # Test composer.lock files
+│   ├── testComparingComplex/ # Complex change scenarios
+│   ├── testDrupal/           # Real Drupal upgrade data
+│   └── [scenario-name]/      # Various test cases
+└── *Test.php                 # Unit tests for each class
+```

README.md

@@ -12,49 +12,87 @@
 [![GitHub License](https://img.shields.io/github/license/jbzoo/composer-diff)](https://github.com/JBZoo/Composer-Diff/blob/master/LICENSE)
 
 
+A powerful CLI tool for visualizing changes in Composer dependencies after running `composer update`. Compare two `composer.lock` files and see exactly what packages were added, removed, upgraded, or downgraded with beautiful output formatting and direct links to changelogs.
+
+## Table of Contents
+
 <!--ts-->
-   * [Why?](#why)
+   * [Features](#features)
    * [Installation](#installation)
-   * [Usage](#usage)
+      * [Via Composer (Recommended)](#via-composer-recommended)
+      * [Standalone PHAR](#standalone-phar)
+   * [Basic Usage](#basic-usage)
    * [Help Description](#help-description)
    * [Output Examples](#output-examples)
       * [Default view (--output=console)](#default-view---outputconsole)
       * [Markdown Output (--output=markdown)](#markdown-output---outputmarkdown)
       * [JSON Output (--output=json)](#json-output---outputjson)
+   * [Advanced Usage](#advanced-usage)
+      * [Compare Specific Files](#compare-specific-files)
+      * [Environment Filtering](#environment-filtering)
+      * [Output Formatting](#output-formatting)
+      * [Real-world Examples](#real-world-examples)
+   * [Requirements](#requirements)
+   * [Architecture](#architecture)
+      * [Change Detection Logic](#change-detection-logic)
+      * [Supported Git Platforms](#supported-git-platforms)
+   * [Development](#development)
+      * [Setup](#setup)
+      * [Testing](#testing)
+      * [Building PHAR](#building-phar)
    * [Roadmap](#roadmap)
-   * [Unit tests and check code style](#unit-tests-and-check-code-style)
    * [License](#license)
    * [See Also](#see-also)
 <!--te-->
 
 
-## Why?
-
-See what packages have been changed after you run `composer update` by comparing `composer.lock` to the `git show HEAD:composer.lock`.
+## Features
 
+- **Visual Dependency Tracking**: See exactly what changed after `composer update` with color-coded output
+- **Multiple Output Formats**: Console tables, Markdown for PRs, or JSON for automation and CI/CD pipelines
+- **Smart Version Detection**: Automatically detects upgrades, downgrades, new, removed, and changed packages
+- **Direct Links to Changes**: Generates comparison URLs for GitHub, GitLab, and Bitbucket repositories
+- **Environment Filtering**: Compare production (`require`) and development (`require-dev`) dependencies separately or together
+- **Git Integration**: Compare current lock file with any git reference (HEAD, branches, tags)
+- **Dev Package Support**: Handles dev branches with commit hash detection and comparison
+- **CI/CD Friendly**: Perfect for automated workflows, deployment pipelines, and Pull Request automation
+- **PHAR Distribution**: Standalone executable or Composer installation options
 
 ## Installation
 
-```shell
-composer require        jbzoo/composer-diff # For specific project
-composer global require jbzoo/composer-diff # As global tool
+### Via Composer (Recommended)
+
+```bash
+# Install for specific project
+composer require jbzoo/composer-diff
+
+# Install globally
+composer global require jbzoo/composer-diff
+```
+
+### Standalone PHAR
 
-# OR use phar file.
+```bash
+# Download latest release
 wget https://github.com/JBZoo/Composer-Diff/releases/latest/download/composer-diff.phar
+
+# Make it executable
+chmod +x composer-diff.phar
 ```
 
-## Usage
+## Basic Usage
 
 ```bash
+# Update your dependencies first
 composer update
 
-# if it's installed via composer
-php ./vendor/bin/composer-diff
-
-# OR (if installed globally)
+# Show what changed (compares HEAD:composer.lock with ./composer.lock)
 composer-diff
 
-# OR (if you downloaded phar file)
+# If installed locally in project
+php ./vendor/bin/composer-diff
+
+# If using PHAR file
 php composer-diff.phar
 ```
 
@@ -215,6 +253,128 @@ Rendered in your readme or PR/MR description:
 ```
 
 
+## Advanced Usage
+
+### Compare Specific Files
+```bash
+# Compare two specific composer.lock files
+composer-diff --source="old/composer.lock" --target="new/composer.lock"
+
+# Compare Git references
+composer-diff --source="HEAD~1:composer.lock" --target="HEAD:composer.lock"
+
+# Compare with specific branch or tag
+composer-diff --source="v1.0.0:composer.lock" --target="./composer.lock"
+```
+
+### Environment Filtering
+```bash
+# Production dependencies only
+composer-diff --env=require
+
+# Development dependencies only
+composer-diff --env=require-dev
+
+# Both environments (default)
+composer-diff --env=both
+```
+
+### Output Formatting
+```bash
+# Markdown output for Pull Requests
+composer-diff --output=markdown
+
+# JSON output for automation
+composer-diff --output=json
+
+# Hide comparison links
+composer-diff --no-links
+
+# Strict mode (exit code 1 if differences found)
+composer-diff --strict
+```
+
+### Real-world Examples
+```bash
+# Generate PR description after update
+composer update
+composer-diff --output=markdown >> pr-description.md
+
+# CI/CD pipeline check
+composer-diff --strict --output=json > changes.json
+
+# Compare major version upgrades
+composer-diff --source="tags/v1.0:composer.lock" --target="tags/v2.0:composer.lock"
+```
+
+## Requirements
+
+- **PHP**: ^8.2
+- **Extensions**: ext-json, ext-filter
+- **Composer**: ^2.0 (for development)
+
+## Architecture
+
+The tool is built with a clean, object-oriented architecture:
+
+- **`DiffAction`**: Main CLI command handler (Symfony Console)
+- **`Comparator`**: Orchestrates comparison between composer.lock files
+- **`ComposerLock`**: Parses and manages composer.lock data
+- **`Package`**: Represents individual packages with version handling
+- **`Diff`**: Compares package versions and determines change types
+- **`Url`**: Generates comparison URLs for Git hosting platforms
+- **Renderers**: Multiple output formats (Console, Markdown, JSON)
+
+### Change Detection Logic
+
+The tool intelligently categorizes changes:
+
+- **New**: Package added to dependencies
+- **Removed**: Package removed from dependencies
+- **Upgraded**: Semantic version increased (1.0.0 → 2.0.0)
+- **Downgraded**: Semantic version decreased (2.0.0 → 1.0.0)
+- **Changed**: Dev branches with different commit hashes
+- **Same**: No changes (filtered out by default)
+
+### Supported Git Platforms
+
+Automatically generates comparison URLs for:
+
+- **GitHub**: `github.com/user/repo/compare/v1.0.0...v2.0.0`
+- **GitLab**: `gitlab.com/user/repo/compare/v1.0.0...v2.0.0`
+- **Bitbucket**: `bitbucket.org/user/repo/branches/compare/v1.0.0%0Dv2.0.0`
+
+## Development
+
+### Setup
+```bash
+# Clone and install dependencies
+git clone https://github.com/JBZoo/Composer-Diff.git
+cd Composer-Diff
+make build
+```
+
+### Testing
+```bash
+# Run all tests
+make test-all
+
+# Run specific test suites
+make test          # PHPUnit tests
+make test-drupal   # Real Drupal upgrade test
+make test-manual   # Manual output examples
+make codestyle     # Code quality checks
+```
+
+### Building PHAR
+```bash
+# Build standalone PHAR executable
+make build-phar
+
+# Create symlink for local testing
+make create-symlink
+```
+
 ## Roadmap
 
  * [ ] Supporting Drupal repos. [For example](https://git.drupalcode.org/project/fast_404).