docs(README): add 'Hierarchical Subscopes' section and update structure for advanced features clarity

cherrypick/README.md

@@ -5,7 +5,7 @@ It provides an easy-to-use system for registering, scoping, and resolving depend
 
 ---
 
-### Fast Dependency Lookup (Performance Improvement)
+### Performance Improvements
 
 > **Performance Note:**  
 > **Starting from version 3.0.0**, CherryPick uses a Map-based resolver index for dependency lookup. This means calls to `resolve<T>()` and related methods are now O(1) operations, regardless of the number of modules or bindings in your scope. Previously, the library had to iterate over all modules and bindings to locate the requested dependency, which could impact performance as your project grew.
@@ -553,7 +553,52 @@ scope.installModules([...]);
 - [x] Comprehensive logging of dependency injection state and actions
 - [x] Automatic resource cleanup for all registered Disposable dependencies
 
-## Quick Guide: Circular Dependency Detection
+---
+
+## Hierarchical Subscopes
+
+CherryPick supports a hierarchical structure of scopes, allowing you to create complex and modular dependency graphs for advanced application architectures. Each subscope inherits from its parent, enabling context-specific overrides while still allowing access to global or shared services.
+
+### Key Points
+
+- **Subscopes** are child scopes that can be opened from any existing scope (including the root).
+- Dependencies registered in a subscope override those from parent scopes when resolved.
+- If a dependency is not found in the current subscope, the resolution process automatically searches parent scopes up the hierarchy.
+- Subscopes can have their own modules, lifetime, and disposable objects.
+- You can nest subscopes to any depth, modeling features, flows, or components independently.
+
+### Example
+
+```dart
+final rootScope = CherryPick.openRootScope();
+rootScope.installModules([AppModule()]);
+
+// Open a hierarchical subscope for a feature or page
+final userFeatureScope = rootScope.openSubScope('userFeature');
+userFeatureScope.installModules([UserFeatureModule()]);
+
+// Dependencies defined in UserFeatureModule will take precedence
+final userService = userFeatureScope.resolve<UserService>();
+
+// If not found in the subscope, lookup continues in the parent (rootScope)
+final sharedService = userFeatureScope.resolve<SharedService>();
+
+// You can nest subscopes
+final dialogScope = userFeatureScope.openSubScope('dialog');
+dialogScope.installModules([DialogModule()]);
+final dialogManager = dialogScope.resolve<DialogManager>();
+```
+
+### Use Cases
+
+- Isolate feature modules, flows, or screens with their own dependencies.
+- Provide and override services for specific navigation stacks or platform-specific branches.
+- Manage the lifetime and disposal of groups of dependencies independently (e.g., per-user, per-session, per-component).
+
+**Tip:** Always close subscopes when they are no longer needed to release resources and trigger cleanup of Disposable dependencies.
+
+
+## Circular Dependency Detection
 
 CherryPick can detect circular dependencies in your DI configuration, helping you avoid infinite loops and hard-to-debug errors.
 
@@ -629,7 +674,7 @@ try {
 **A:**  
 Yes! Even if none of your services currently implement `Disposable`, always use `await` when closing scopes. If you later add resource cleanup (by implementing `dispose()`), CherryPick will handle it automatically without you needing to change your scope cleanup code. This ensures resource management is future-proof, robust, and covers all application scenarios.
 
-## Documentation
+## Documentation Links
 
 - [Circular Dependency Detection (English)](doc/cycle_detection.en.md)
 - [Обнаружение циклических зависимостей (Русский)](doc/cycle_detection.ru.md)