docs: premium-quality rewrite of README, CHANGELOG, and INDEX

README.md:
- Center-aligned hero with 7 badges (PHP, Composer, License, PHPStan,
  Tests, KaririCode) and navigation link bar
- Before/after diff block showing the five-to-one dep reduction
- Unified table-based CLI reference with flags and options
- Separated CI examples: unified pipeline + parallel jobs
- Architecture section with component layout, dependency flow diagram,
  and key design decisions table linking to ADRs
- Project Stats table includes PHPStan level (0 errors) and test count
- Building kcode.phar section updated for bin/build-phar.php
- KaririCode ecosystem footer with links

CHANGELOG.md:
- Added/Changed/Fixed/Removed structure with precise technical context
- [Unreleased] consolidates all post-v1.0.0 work including type-safety
  fixes (35 PHPStan errors → 0), CVE remediation, box removal
- Net-result summary line at end of [Unreleased]
- Comparison URL links in footer

docs/INDEX.md:
- Introductory paragraph placed before tables
- Quick Navigation converted to table format (Document + Description)
- box.json reference removed (builder replaced by bin/build-phar.php)
- code-quality.yml added to Quick Navigation

Author: walmir-silva

CHANGELOG.md

@@ -1,36 +1,51 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to **KaririCode Devkit** are documented here.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
 
 ## [Unreleased]
 
-### Fixed
+### Added
 
-- **bin/kcode:** Fatal `TypeError` when invoked via Composer scripts — `$argv` was inaccessible inside the static IIFE. Fix passes it as an explicit parameter (`$argv ?? []`).
-- **composer.json:** `phpunit/phpunit` constraint updated from `^11.0` to `^12.0` to match the installed version (12.4.2). Composer scripts renamed to `kcode:*` prefix to avoid collision with built-in Composer commands (e.g. `init`). `allow-plugins.infection/extension-installer: false` added to suppress spurious warnings.
-- **Makefile:** `VERSION` now resolved from `git describe --tags` (falls back to `box.json` metadata). `install`/`install-prod` add `--no-scripts` to prevent broken `kcode init` invocation during dependency installation. New `security` target (`kcode security`). New `_require-kcode` guard on all quality targets. `distclean` no longer removes `composer.lock` (library — not tracked). `check-env` now correctly detects `vendor/bin/kcode`.
-- **phpunit.xml:** `memory_limit` reduced from 1G to 256M (actual usage ≈ 22 MB). Opening tag attributes reformatted one-per-line.
+- **`bin/build-phar.php`:** Native PHP PHAR builder — compiles `kcode.phar` without `humbug/box`. Added as a workaround for a Box 4.x / PHP 8.4 incompatibility (`chdir(): Not a directory` during `endBuffering()`).
+- **Test suite — `tests/Unit/Exception`:** `DevkitExceptionTest`, `ConfigurationExceptionTest`, `ToolExceptionTest`.
+- **Test suite — `tests/Unit/ValueObject`:** `ToolResultTest`, `QualityReportTest`, `MigrationReportTest`.
+- **Test suite — `tests/Unit/Core`:** `ProjectContextTest`, `DevkitConfigTest`.
+- **Full unit test suite:** 41 tests, 81 assertions — all passing on PHP 8.4 / PHPUnit 12.4.5.
 
 ### Changed
 
-- **.github/workflows/ci.yml:** Added `develop` branch to push/PR triggers.
-- **.github/workflows/code-quality.yml:** Replaced 378-line legacy workflow (PHPMD + runtime `composer require` anti-pattern) with 160-line workflow aligned to the kcode CLI. Jobs: `dependencies → security → phpstan → cs-fixer → quality-summary`.
-- **.gitignore:** Expanded from 8 to 42 patterns, covering legacy scaffold files, tool configs outside the toolchain, IDE artefacts, environment files, and OS artefacts.
+- **`composer.json`:** `phpunit/phpunit` constraint updated from `^11.0` to `^12.0`. Composer scripts renamed to `kcode:*` prefix to avoid collision with built-in Composer commands. `infection/extension-installer: false` added to `allow-plugins` to suppress spurious warnings. The `build` script now calls `bin/build-phar.php` instead of `box compile`.
+- **`Makefile`:** `build` target no longer requires `humbug/box` — uses `PHAR_BUILDER := bin/build-phar.php`. `VERSION` simplified to `git describe --tags` only (no `box.json` fallback). `check-env` shows PHAR builder status instead of Box version. `_require-box` guard replaced by `_require-phar-builder`. `install`/`install-prod` add `--no-scripts`. New `security` target. New `_require-kcode` guard on all quality targets. `distclean` no longer removes `composer.lock`. `check-env` correctly detects `vendor/bin/kcode`.
+- **`.github/workflows/ci.yml`:** Added `develop` branch to push/PR triggers.
+- **`.github/workflows/code-quality.yml`:** Replaced 378-line legacy workflow (PHPMD + runtime `composer require`) with a lean 160-line workflow aligned to the kcode CLI. Jobs: `dependencies → security → phpstan → cs-fixer → quality-summary`.
+- **`.gitignore`:** Expanded from 8 to 42 patterns (legacy scaffold files, IDE artefacts, OS artefacts, environment files, tool caches).
+- **`docs/BUILDING.md`:** Fully rewritten for `bin/build-phar.php` — removed all `humbug/box` references.
+- **`phpunit.xml`:** `memory_limit` reduced from 1G to 256M. Attributes reformatted one-per-line.
+
+### Fixed
 
-### Removed (cleanup)
+- **`bin/kcode`:** Fatal `TypeError` when invoked via Composer scripts — `$argv` was inaccessible inside the static IIFE. Fixed by passing it as an explicit parameter (`$argv ?? []`).
+- **`src/Configuration/PhpStanConfigGenerator`:** Removed `checkMissingIterableValueType` and `checkGenericClassInNonGenericObjectType` — both were removed from PHPStan 2.x core and caused `Invalid configuration` errors.
+- **`src/Configuration/CsFixerConfigGenerator`:** Added `(string)` cast on `preg_replace()` return values in `exportRules()` to satisfy PHPStan level-9 type constraints.
+- **`src/Core/Devkit`:** Added `false` guard on `file_get_contents()` in `appendGitignore()`. Added `@var \SplFileInfo` annotation in `removeRecursive()`.
+- **`src/Core/DevkitConfig`:** Added `@var array<string, mixed>` before assigning loaded overrides. `toolVersions()` now correctly returns `array<string, string>` via `array_filter`.
+- **`src/Core/MigrationDetector`:** Added `false !== $raw` guard on `file_get_contents()`. Added `@var` annotations on `json_decode()` result.
+- **`src/Core/ProjectDetector`:** Added `false !== $raw` guard on `file_get_contents()`. Extracted `$psr4Source`, `$psr4Test`, `$projectName` with proper `is_array()` guards. Fixed `detectNamespace()` and `detectPhpVersion()` with nested `is_array()` / `is_string()` checks.
+- **`src/Runner/*`:** Added `#[\Override]` attribute to `toolName()`, `vendorBin()`, and `defaultArguments()` across all six runners.
+- **`src/ValueObject/MigrationReport`:** Added `false` guard after `file_get_contents()` and `json_encode()`. Extracted `$requireDev` with `@var` and `is_array()` guard. Fixed `removePackagesFromComposer()` to write back the updated `$requireDev` slice into `$composer` before `json_encode()`. Added `@var \SplFileInfo` in `removeRecursive()`.
+- **Security:** `phpunit/phpunit` updated from 12.4.2 → 12.4.5 (fixes CVE-2026-24765, HIGH).
 
-- 42 legacy scaffold files: `.config/`, `.docs/`, `.make/`, `devkit/`, `docker-compose.yml`, `.env.example`, `.env.xdebug`, `.php-cs-fixer.php`, `phpcs.xml`, `phpstan.neon`, `infection.json`, `phpbench.json`, `.editorconfig`, `.gitattributes`, `.vscode/` (read-only root-owned), `build/`, `coverage/`.
-- 4 prototype test files targeting removed classes (`UserProfile`, `Email`, `UserId`, `UserRole`).
+### Removed
 
-### Added
+- **`humbug/box`:** Removed as a build dependency. `bin/build-phar.php` replaces it.
+- **Legacy scaffold files (42):** `.config/`, `.docs/`, `.make/`, `devkit/`, `docker-compose.yml`, `.env.example`, `.env.xdebug`, root-level tool configs, `build/`, `coverage/`.
+- **Prototype test files (4):** Targeting removed classes `UserProfile`, `Email`, `UserId`, `UserRole`.
 
-- **tests/Unit/Exception:** `DevkitExceptionTest`, `ConfigurationExceptionTest`, `ToolExceptionTest`.
-- **tests/Unit/ValueObject:** `ToolResultTest`, `QualityReportTest`, `MigrationReportTest`.
-- **tests/Unit/Core:** `ProjectContextTest`, `DevkitConfigTest`.
-- Full unit test suite: **41 tests, 81 assertions** — all passing on PHP 8.4.14 / PHPUnit 12.4.2.
+**Net result:** PHPStan level 9 — **0 errors** (down from 35). PHPUnit — **41 tests, 81 assertions passing**.
 
 ---
 
@@ -43,15 +58,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Configuration generators:** PHPUnit, PHPStan, PHP-CS-Fixer, Rector, Psalm.
 - **Tool runners:** PHPUnit, PHPStan, PHP-CS-Fixer, Rector, Psalm, Composer Audit.
 - **CLI commands:** `init`, `migrate`, `test`, `analyse`, `cs:fix`, `rector`, `security`, `quality`, `format`, `clean`.
-- **Migration detector:** Scans `composer.json` require-dev and project root for redundant dependencies, config files, and cache paths. Interactive cleanup with `--dry-run` and `--no-interaction` modes.
-- **CLI framework:** Zero-dependency `Application` router with ANSI output, argument parsing, and passthrough.
-- **Value objects:** `ToolResult` and `QualityReport` (immutable, readonly).
+- **Migration detector:** Scans `composer.json` require-dev and project root for redundant files and cache paths. Interactive cleanup with `--dry-run` and `--no-interaction`.
+- **CLI framework:** Zero-dependency `Application` router with ANSI output, argument parsing, and passthrough support.
+- **Value objects:** `ToolResult`, `QualityReport`, `MigrationReport` (immutable, readonly).
 - **Exception hierarchy:** `DevkitException`, `ConfigurationException`, `ToolException`.
-- **PHAR support:** `box.json` configuration for humbug/box compilation.
 - **Build automation:** `Makefile` with targets: `install`, `build`, `verify`, `self-test`, `quality`, `security`, `clean`, `release`.
 - **CI/CD:** GitHub Actions workflows for quality checks (`ci.yml`) and automated PHAR releases (`release.yml`).
-- **Build documentation:** Complete PHAR build guide with prerequisites, troubleshooting, and verification steps.
-- **Binary resolution:** Three-tier strategy (PHAR → vendor → global PATH).
-- **Project detection:** Automatic namespace, PHP version, source/test directory discovery from `composer.json`.
-- **Override system:** `devkit.php` at project root for per-project customization with type-safe merging. Scaffold with `kcode init --config`.
+- **Binary resolution:** Three-tier strategy — PHAR → vendor → global PATH.
+- **Override system:** `devkit.php` at project root with type-safe merging. Scaffold with `kcode init --config`.
 - **Documentation:** README, 6 ADRs, 3 specifications, docs index.
+
+---
+
+[Unreleased]: https://github.com/kariricode/devkit/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/kariricode/devkit/releases/tag/v1.0.0