docs: Add AI guidance and improve project docs

.gitignore

@@ -17,6 +17,7 @@ vendor
 phpunit.xml
 composer.lock
 *.cache
+.claude
 
 # Cutline
 SkeletonPhp*

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 Skeleton-Php is a project skeleton template for creating new PHP libraries within the JBZoo ecosystem. This is not a completed library but a template that gets transformed into a new project via the `create-new-project.php` script.
+
+## Architecture
+
+### Skeleton System
+- **Template transformation**: The project uses placeholder tokens (`__PACKAGE__`, `__NS__`, etc.) that get replaced during project creation
+- **Self-destructing setup script**: `create-new-project.php` transforms the skeleton and then deletes itself
+- **Namespace mapping**: Template files like `src/__NS__.php` get renamed to actual class names during setup
+
+### Core Structure
+- `src/` - Main library code with skeleton classes
+- `tests/` - PHPUnit tests extending JBZoo's testing framework
+- Template files use `__NS__` and `__PACKAGE__` placeholders that get replaced during project initialization
+
+## Common Commands
+
+### Development
+```bash
+make update          # Install/update all dependencies
+make autoload        # Dump optimized autoloader
+```
+
+### Testing
+```bash
+make test           # Run PHPUnit tests
+make test-all       # Run all tests and code style checks
+make codestyle      # Run all linters at once
+```
+
+### Individual QA Tools
+```bash
+make test-phpstan        # Static analysis with PHPStan
+make test-psalm          # Static analysis with Psalm
+make test-phpcsfixer     # Check PHP-CS-Fixer rules
+make test-phpcsfixer-fix # Auto-fix with PHP-CS-Fixer
+make test-phpmd          # Mess detector
+make test-phan          # Phan static analyzer
+make test-composer       # Validate composer files
+```
+
+### Project Creation
+```bash
+php create-new-project.php YourPackageName  # Transform skeleton into new project
+make skel-test          # Test the skeleton transformation process
+```
+
+## JBZoo Standards
+
+### PHP Requirements
+- PHP 8.2+ required (`composer.json` specifies `"php": "^8.2"`)
+- Strict types declaration required (`declare(strict_types=1)`)
+- PSR-4 autoloading with `JBZoo\` namespace prefix
+
+### Testing Framework
+Tests extend JBZoo's testing framework classes:
+- `AbstractPackageTest` - For package-level tests (validates structure, composer.json, etc.)
+- Standard PHPUnit tests for functionality
+- Uses custom assertion helpers like `isSame()` instead of `assertEquals()`
+
+### Code Style
+Uses JBZoo Codestyle package (`jbzoo/toolbox-dev`) which includes:
+- PHP-CS-Fixer with custom JBZoo rules
+- PHPStan for static analysis
+- Psalm for additional static analysis
+- PHPMD for mess detection
+- PSR-12 compliance
+
+## File Structure Notes
+
+### Template Files
+- `src/__NS__.php` → Gets renamed to actual namespace class during setup
+- `tests/__NS__Test.php` → Becomes the main test class
+- `tests/__NS__PackageTest.php` → Package validation tests
+
+### Configuration
+- `phpunit.xml.dist` - PHPUnit configuration with coverage reporting
+- `Makefile` - Includes JBZoo's codestyle Makefiles for consistent tooling
+- `.phan.php` - Phan static analyzer configuration
+
+### Build System
+The project uses JBZoo's sophisticated Makefile system:
+- Main `Makefile` includes `vendor/jbzoo/codestyle/src/init.Makefile`
+- Provides unified commands across all JBZoo projects
+- Supports both local development and CI environments
+
+## Development Workflow
+
+1. **For new projects**: Use `php create-new-project.php PackageName` to transform skeleton
+2. **For skeleton development**: Use `make skel-test` to test the transformation process
+3. **Always run**: `make test-all` before committing to ensure all QA checks pass
+4. **For fixes**: Use `make test-phpcsfixer-fix` to auto-fix code style issues
+
+## CI Integration
+
+- GitHub Actions workflow in `.github/workflows/main.yml`
+- Automated testing across multiple PHP versions
+- Coverage reporting integration with Coveralls
+- All QA tools run in CI pipeline

README.md

@@ -2,19 +2,109 @@
 
 [![CI](https://github.com/JBZoo/Skeleton-Php/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/JBZoo/Skeleton-Php/actions/workflows/main.yml?query=branch%3Amaster)    [![Coverage Status](https://coveralls.io/repos/github/JBZoo/Skeleton-PHP/badge.svg?branch=master)](https://coveralls.io/github/JBZoo/Skeleton-PHP?branch=master)    [![Psalm Coverage](https://shepherd.dev/github/JBZoo/Skeleton-Php/coverage.svg)](https://shepherd.dev/github/JBZoo/Skeleton-Php)    [![Psalm Level](https://shepherd.dev/github/JBZoo/Skeleton-Php/level.svg)](https://shepherd.dev/github/JBZoo/Skeleton-Php)    [![CodeFactor](https://www.codefactor.io/repository/github/jbzoo/skeleton-php/badge)](https://www.codefactor.io/repository/github/jbzoo/skeleton-php/issues)
 
+## Overview
 
-This is not a completed library, but only a blank.
-It aims to clean up the minds of programmers and standardize the development of open-source libraries for JBZoo.
+This is a project skeleton template for creating new PHP libraries within the JBZoo ecosystem. It's not a completed library but a standardized template that helps maintain consistency across JBZoo projects.
 
+The skeleton includes:
+- Modern PHP 8.2+ setup with strict typing
+- Comprehensive testing framework integration
+- Complete CI/CD pipeline configuration
+- Integrated code quality tools (PHPStan, Psalm, PHP-CS-Fixer, etc.)
+- JBZoo coding standards and conventions
 
-### Action items
+## Quick Start
 
- * Create a new repository (MIT, without .gitignore).
- * Make a checkout of a clean repository for a working machine.
- * [Download the latest version of the skeleton](https://github.com/JBZoo/Skeleton/archive/master.zip).
- * Run the skeleton script for your package through `php ./create-new-project.php Skeleton-Php`
+### Creating a New Project
 
+1. **Create a new repository** (MIT license, without .gitignore)
+2. **Clone the skeleton**:
+   ```bash
+   git clone https://github.com/JBZoo/Skeleton-Php.git your-project-name
+   cd your-project-name
+   ```
+3. **Initialize the project**:
+   ```bash
+   make update
+   php create-new-project.php Project-Name
+   make update
+   ```
 
-### License
+The initialization script will:
+- Replace all template placeholders with your package name
+- Rename template files to match your namespace
+- Update composer.json and other configuration files
+- Clean up skeleton-specific files
+
+### Development Commands
+
+```bash
+# Install/update dependencies
+make update
+
+# Develop cycle
+make skel-test
+
+# fix, commit, git reset --hard, repeat.
+
+# Run all tests and code quality checks
+make test-all
+
+# Run individual tools
+make test           # PHPUnit tests
+make codestyle      # All linters
+```
+
+## Project Structure
+
+```
+├── src/                    # Main library code
+├── tests/                  # PHPUnit tests
+├── create-new-project.php  # Skeleton transformation script
+├── Makefile               # Build commands
+├── phpunit.xml.dist       # PHPUnit configuration
+└── composer.json          # Dependencies and autoloading
+```
+
+## Template System
+
+The skeleton uses placeholder tokens that get replaced during project creation:
+
+- `__PACKAGE__` → Your package name (e.g., "MyAwesomeLib")
+- `__NS__` → Your namespace (e.g., "MyAwesomeLib")
+- `jbzoo/skeleton-php` → Your composer package name
+
+Template files that get renamed:
+- `src/__NS__.php` → `src/YourClassName.php`
+- `tests/__NS__Test.php` → `tests/YourClassNameTest.php`
+
+## Requirements
+
+- PHP 8.2 or higher
+- Composer 2.0+
+- Make (for build commands)
+
+## Code Quality
+
+The skeleton includes comprehensive code quality tools:
+
+- **PHPUnit** - Unit testing framework
+- **PHPStan** - Static analysis (level max)
+- **Psalm** - Additional static analysis
+- **PHP-CS-Fixer** - Code style fixer
+- **PHPMD** - Mess detector
+- **Phan** - Static analyzer
+
+All tools are pre-configured with JBZoo standards and integrate with CI/CD pipelines.
+
+## CI/CD
+
+The skeleton includes GitHub Actions workflow that:
+- Tests against multiple PHP versions
+- Runs all quality assurance tools
+- Generates coverage reports
+- Validates composer configuration
+
+## License
 
 MIT

create-new-project.php

@@ -116,7 +116,8 @@ function getFileList(string $dir, array &$results = []): array
 }
 
 // Self-destruction
-@\unlink(__FILE__);
+\unlink(__DIR__ . '/CLAUDE.md');
+\unlink(__FILE__);
 
 // Success
 echo $packageName . ' is ready!' . \PHP_EOL;