docs: add kun-init 4-file documentation structure

AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+Steering notes for AI agents working in this repository. For install and usage see [README.md](README.md); for development setup, testing, and the contribution process see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## What This Is
+
+`kununu/collections` is a PHP library that reduces the boilerplate involved in building typed collections on top of `ArrayIterator`. It is consumed as a Composer package (`composer require kununu/collections`) and has no runtime application, service, or deployment.
+
+## Domain
+
+The library provides interfaces, traits, and abstract base classes for:
+
+- Collections backed by `ArrayIterator` (basic and filterable).
+- Converting collection items to and from `array`, `string`, `int`, and `Stringable`.
+- Comparing collection items.
+- Filtering and grouping collection data.
+- Key/value structures, including enum-keyed variants.
+- Building items and mapping between representations.
+
+## Code Layout
+
+- `src/` — library source, PSR-4 under `Kununu\Collection\`.
+  - `Convertible/`, `Comparable/` — conversion and comparison interfaces.
+  - `Filter/` — filtering and grouping primitives.
+  - `EnumKeyValue/` — enum-keyed key/value support and its exceptions.
+  - `AbstractItemBuilderTraits/`, `Mapper/`, `Helper/`, `Exception/` — item builders, mapping, helpers, and exceptions.
+  - `TestCase/` — `AbstractCollectionTestCase` for consumers testing their own collections.
+- `tests/` — PHPUnit tests, PSR-4 under `Kununu\Collection\Tests\`.
+- `docs/` — per-feature documentation referenced from the README.
+
+## Quality Gates
+
+All of the following must pass. Run them via the Composer scripts:
+
+- `composer cs` — PHP CS Fixer (kununu coding standards).
+- `composer sniffer` — PHP_CodeSniffer.
+- `composer phpstan` — PHPStan.
+- `composer rector` — Rector (dry-run).
+- `composer test` — PHPUnit.
+
+See the `scripts` section of `composer.json` for the complete list.
+
+## Hard Constraints
+
+- The PHP version is pinned in `composer.json` (`require.php`); do not lower it.
+- Keep the public API stable. This library follows semantic versioning; API changes require a corresponding `CHANGELOG.md` entry.
+- Every code change must be covered by tests.
+- Respect the existing coding standards; do not bypass the quality gates.
+- Runtime code may depend only on PHP and `ext-mbstring`; keep other tooling in `require-dev`.
+
+## Deep Documentation
+
+Feature-level details live in `docs/` (collection interfaces, traits, convertibles, mappers, key/value, and the test case). Start from the links in [README.md](README.md).

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -4,20 +4,56 @@ Contributions are more than **welcome**.
 
 We accept contributions via Pull Requests on [GitHub](https://github.com/kununu/collections).
 
+## Development Setup
+
+Install the dependencies:
+
+```bash
+composer install
+```
+
+The required PHP version is pinned in `composer.json` (`require.php`). Development tooling (PHPUnit, PHPStan, Rector, and the kununu coding standards) is installed as dev dependencies.
+
+## Testing
+
+Run the test suite:
+
+```bash
+composer test
+```
+
+Run the tests with a coverage report:
+
+```bash
+composer test-coverage
+```
+
+## Quality Gates
+
+The following checks run in CI and must pass before a pull request can be merged. They can be run locally through the corresponding Composer scripts:
+
+- `composer cs` — PHP CS Fixer with the kununu coding standards
+- `composer sniffer` — PHP_CodeSniffer (`composer sniffer-fix` to auto-fix)
+- `composer phpstan` — PHPStan static analysis
+- `composer rector` — Rector in dry-run mode (`composer rector-fix` to apply)
+- `composer test` — PHPUnit test suite
+
+See the `scripts` section of `composer.json` for the full list. CI additionally runs `composer-dependency-analyser`, `composer-require-checker`, and `composer-normalize`.
+
 ## Pull Requests
 
-- **[kununu Coding Standards](https://github.com/kununu/code-tools)** - The kununu coding standards are an extension of the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md). Check out [kununu Coding Standards](https://github.com/kununu/code-tools) for more details. In development mode the package [kununu/code-tools](https://github.com/kununu/code-tools) is already a dependency that expose commands that you can use to meet our standards.
+- **[kununu Coding Standards](https://github.com/kununu/code-tools)** — The kununu coding standards are an extension of the [PSR-2](https://github.com/php-fig/fig-standards/blob/main/accepted/PSR-2-coding-style-guide.md). The [kununu/code-tools](https://github.com/kununu/code-tools) package is already a dev dependency and exposes the commands you need to meet our standards.
 
-- **Add tests!** - to ensure a high quality code base, your code patch can't be accepted if it does not have tests.
+- **Add tests!** — To ensure a high quality code base, your code patch can't be accepted if it does not have tests.
 
-- **Document any change in behaviour** - Make sure the `CHANGELOG.md`, `README.md` and any other relevant documentation are kept up-to-date.
+- **Document any change in behaviour** — Make sure the `CHANGELOG.md`, `README.md`, and any other relevant documentation are kept up-to-date.
 
-- **Consider our release cycle** - Since we're using semantic versioning ([SemVer v2.0.0](http://semver.org/)). Changes to the API must be done with great consideration, and prevented if at all possible.
+- **Consider our release cycle** — We use semantic versioning ([SemVer v2.0.0](https://semver.org/)). Changes to the API must be done with great consideration, and prevented if at all possible.
 
-- **Create feature branches** - Master is the stable branch, create a new branch for each feature.
+- **Create feature branches** — `main` is the stable branch, create a new branch for each feature.
 
-- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
+- **One pull request per feature** — If you want to do more than one thing, send multiple pull requests.
 
-- **Be respectful** - Be excellent to other contributors. See our [Code of Conduct](CODE_OF_CONDUCT.md).
+- **Be respectful** — Be excellent to other contributors. See our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 **Happy coding**!

README.md

@@ -10,29 +10,6 @@ You can use this library by issuing the following command:
 composer require kununu/collections
 ```
 
-## Running Tests
-
-Run the tests by doing:
-
-```bash
-composer install
-vendor/bin/phpunit
-```
-
-or
-
-```bash
-composer install
-composer test
-```
-
-To run test and generate coverage information:
-
-```bash
-composer install
-composer test-coverage
-```
-
 ## Usage
 
 The library defines interfaces to deal with collections and also boilerplate code with default implementations.
@@ -61,12 +38,11 @@ More details:
 
 See [CHANGELOG.md](CHANGELOG.md) for the list of notable changes in each release.
 
-## Contribute
+## Contributing
 
-If you are interested in contributing read our [contributing guidelines](/CONTRIBUTING.md).
+If you are interested in contributing read our [contributing guidelines](CONTRIBUTING.md).
 
 ------------------------------
 
 ![Continuous Integration](https://github.com/kununu/collections/actions/workflows/continuous-integration.yml/badge.svg)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kununu_collections&metric=alert_status)](https://sonarcloud.io/dashboard?id=kununu_collections)
-