docs: update README with usage examples and benchmarking details; improve security policy wording

refactor: change container property visibility to protected in benchmarks and compiled container

Author: Thavarshan

README.md

@@ -3,6 +3,7 @@
 [![PHP Version](https://img.shields.io/badge/php-%5E8.4-blue)](https://www.php.net/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](tests/)
+[![Coverage](https://img.shields.io/badge/coverage-report-brightgreen)](#testing)
 [![CI](https://github.com/atomic-php/container/actions/workflows/ci.yml/badge.svg)](https://github.com/atomic-php/container/actions)
 [![Codecov](https://codecov.io/gh/atomic-php/container/branch/main/graph/badge.svg)](https://codecov.io/gh/atomic-php/container)
 [![Packagist](https://img.shields.io/packagist/v/atomic/container)](https://packagist.org/packages/atomic/container)
@@ -57,6 +58,8 @@ composer require atomic/container
 
 ## Quick Start
 
+### Basic Usage
+
 ```php
 <?php
 
@@ -87,6 +90,8 @@ $uuid1  = $container->get('uuid');
 $uuid2  = $container->get('uuid'); // different
 ```
 
+Note: This package is framework‑agnostic and can be used with any PSR‑11 consumer.
+
 ## Architecture
 
 ### Core Components
@@ -99,6 +104,20 @@ $uuid2  = $container->get('uuid'); // different
 └────────────────────┘    └───────────────────────┘
 ```
 
+### Compilation Process
+
+1. Boot Time: Builder collects instances, factories and aliases and compiles them into an immutable container.
+2. Runtime: `get()` performs O(1) lookup with alias pre-resolution and lazy singleton caching.
+3. Caching: Shared factories are resolved once and cached on first use.
+
+```php
+// This happens ONCE at boot:
+$container = $builder->compile();
+
+// This happens MILLIONS of times at runtime:
+$service = $container->get('service'); // ⚡ Fast path
+```
+
 ### Resolution Model
 
 1. `alias(id)` → resolve to final target (pre‑resolved at compile)
@@ -158,19 +177,67 @@ composer cs-check
 
 `composer test-coverage` generates `coverage.xml` (Clover) used by CI; the workflow uploads it to Codecov for the badge/report.
 
-## Benchmarks
+## Benchmarking
+
+Measure performance with the built-in benchmark suite:
 
 ```bash
+# Run all benchmarks
 composer benchmark
+
+# View detailed performance metrics
+php benchmarks/run-benchmarks.php
+```
+
+### Benchmark Results
+
+```text
+Container Benchmark:
+benchGetInstance              : 3,409,676 ops/sec (0.000 ms/op)
+benchGetSingleton             : 3,419,738 ops/sec (0.000 ms/op)
+benchGetFactory               : 1,877,929 ops/sec (0.001 ms/op)
+benchGetAlias                 : 3,254,276 ops/sec (0.000 ms/op)
+benchHasHit                   : 3,323,349 ops/sec (0.000 ms/op)
+benchHasMiss                  : 3,132,513 ops/sec (0.000 ms/op)
+
+Compile Benchmark:
+benchCompile5                 :   450,885 ops/sec (0.002 ms/op)
+benchCompile20                :   139,451 ops/sec (0.007 ms/op)
 ```
 
-Includes:
+## Code Quality
+
+Maintain code quality with included tools:
+
+```bash
+# Check code style
+composer cs-check
+
+# Fix code style
+composer cs-fix
+
+# Run static analysis
+composer psalm
+
+# Run all quality checks
+composer qa
+```
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.
+
+## License
 
-- `ContainerBenchmark` — get()/has() performance for instances, singletons, factories, aliases
-- `ContainerCompileBenchmark` — compile time with small/medium registration sets
+This project is licensed under the MIT License — see [LICENSE](LICENSE).
 
-## Notes
+### Test Coverage
 
-- Immutable runtime container: build everything up front via the builder, then share the compiled instance.
-- Aliases are cycle‑checked during compilation; self‑aliasing and cycles throw.
-- The container is intentionally lean and unopinionated; add higher‑level features (e.g., providers/autowiring) in your app layer if desired.
+- Registrations and aliasing (including chains and cycle detection)
+- Singleton caching and factory creation
+- Error propagation (wrapping into ContainerException)
+- Immutability of compiled container

SECURITY.md

@@ -1,4 +1,4 @@
 # Security Policy
 
-Report security issues privately to the maintainers. Do not open public issues for vulnerabilities.
+Report security issues protectedly to the maintainers. Do not open public issues for vulnerabilities.
 

benchmarks/ContainerBenchmark.php

@@ -9,15 +9,15 @@
 
 final class ContainerBenchmark implements BenchmarkInterface
 {
-    private ContainerInterface $container;
+    protected ContainerInterface $container;
 
     public function setUp(): void
     {
-        $b = new ContainerBuilder();
+        $b = new ContainerBuilder;
         $b->set('config', ['env' => 'prod']);
-        $b->set('instance', new \stdClass());
-        $b->set('shared', fn () => new \stdClass(), shared: true);
-        $b->factory('factory', fn () => new \stdClass());
+        $b->set('instance', new \stdClass);
+        $b->set('shared', fn () => new \stdClass, shared: true);
+        $b->factory('factory', fn () => new \stdClass);
         $b->alias('svc', 'shared');
         $this->container = $b->compile();
     }

src/CompiledContainer.php

@@ -19,18 +19,17 @@
 final class CompiledContainer implements ContainerInterface
 {
     /**
-     * @param array<string,mixed> $instances
-     * @param array<string,callable(ContainerInterface):mixed> $sharedFactories
-     * @param array<string,callable(ContainerInterface):mixed> $factories
-     * @param array<string,string> $aliases
+     * @param  array<string,mixed>  $instances
+     * @param  array<string,callable(ContainerInterface):mixed>  $sharedFactories
+     * @param  array<string,callable(ContainerInterface):mixed>  $factories
+     * @param  array<string,string>  $aliases
      */
     public function __construct(
-        private array $instances,
-        private array $sharedFactories,
-        private array $factories,
-        private array $aliases,
-    ) {
-    }
+        protected array $instances,
+        protected array $sharedFactories,
+        protected array $factories,
+        protected array $aliases,
+    ) {}
 
     #[\Override]
     public function get(string $id): mixed
@@ -78,6 +77,7 @@ public function get(string $id): mixed
     public function has(string $id): bool
     {
         $id = $this->aliases[$id] ?? $id;
+
         return \array_key_exists($id, $this->instances)
             || isset($this->sharedFactories[$id])
             || isset($this->factories[$id]);