chore: update documentation and project structure

.gitignore

@@ -6,4 +6,4 @@
 composer.lock
 /.php-cs-fixer.cache
 /.phpstan/
-.junie.json
+.junie

README.md

@@ -4,6 +4,8 @@ Feature flag handling for PHP. Simple, framework-agnostic, and lightweight.
 
 ![CI](https://github.com/getphred/flagpole/actions/workflows/ci.yml/badge.svg)
 ![Packagist](https://img.shields.io/packagist/v/getphred/flagpole.svg)
+[![Total Downloads](https://img.shields.io/packagist/dt/getphred/flagpole.svg?style=flat-square)](https://packagist.org/packages/getphred/pairity)
+[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
 
 ## Installation
 
@@ -27,6 +29,9 @@ $repo = InMemoryFlagRepository::fromArray([
         'enabled' => null,               // not a hard on/off
         'rolloutPercentage' => 25,       // 25% gradual rollout
         'allowList' => ['user_1'],       // always on for specific users
+        'rules' => [                     // attribute-based rules
+            ['attribute' => 'plan', 'operator' => 'eq', 'value' => 'pro'],
+        ],
     ],
     'hard-off' => [ 'enabled' => false ],
     'hard-on'  => [ 'enabled' => true ],
@@ -34,7 +39,7 @@ $repo = InMemoryFlagRepository::fromArray([
 
 $flags = new FeatureManager($repo);
 
-$context = Context::fromArray(['userId' => 'user_42']);
+$context = Context::fromArray(['userId' => 'user_42', 'plan' => 'pro']);
 
 if ($flags->isEnabled('new-dashboard', $context, false)) {
     // show the new dashboard
@@ -47,31 +52,27 @@ if ($flags->isEnabled('new-dashboard', $context, false)) {
 
 - Flag: has a `name` and optional strategies:
   - `enabled`: explicit boolean on/off overrides everything.
-  - `rolloutPercentage`: 0-100 gradual rollout based on a stable hash of the flag name + user key.
   - `allowList`: list of user keys that always get the flag enabled.
+  - `rules`: complex attribute targeting (e.g. `version > 2.0`, `plan == 'pro'`).
+  - `rolloutPercentage`: 0-100 gradual rollout based on a stable hash.
 - Context: attributes about the subject (e.g. `userId`, `email`) used for evaluation.
-- Repository: source of truth for flags. Provided: `InMemoryFlagRepository`. You can implement your own.
+- Repository: source of truth for flags. Provided: `InMemoryFlagRepository`, `JsonFileRepository`.
+- Hydration: `FlagHydrator` centralizes flag creation and provides validation for targeting rules.
+- Observability: Optional PSR-3 logging of evaluation results and reasons.
 
 ## Targeting key
 
 Evaluator looks for a stable key in the context in this order: `key`, `userId`, `id`, `email`.
-
-## Rollout hashing and boundary behavior
-
-- Stable bucketing uses `crc32(flagName:key)` normalized to an unsigned 32-bit integer, then mapped to buckets 0..99.
-- This guarantees consistent behavior across 32-bit and 64-bit platforms.
-- Boundary rules:
-  - 0% rollout always evaluates to `false` when a targeting key is present.
-  - 100% rollout always evaluates to `true` when a targeting key is present.
-  - If no targeting key is present in the `Context`, percentage rollout falls back to the `default` you pass to `isEnabled()`.
+You can also specify an explicit `targetingKey` per flag to use a specific attribute (e.g. `orgId`).
 
 ## Precedence semantics
 
 When evaluating a flag, the following precedence applies:
 1. `allowList` — if the targeting key is in the allow-list, the flag is enabled.
-2. `enabled` — explicit on/off overrides percentage rollout and defaults.
-3. `rolloutPercentage` — uses stable bucketing over the targeting key.
-4. Fallback — returns the provided default when none of the above apply.
+2. `enabled` — explicit on/off overrides everything below.
+3. `rules` — attribute-based targeting rules.
+4. `rolloutPercentage` — uses stable bucketing over the targeting key.
+5. Fallback — returns the provided default when none of the above apply.
 
 ## Framework integration