diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 617374f..d0c7486 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-team@appwrite.io..
+team@appwrite.io.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b4d952d..be2109f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,6 +32,8 @@ composer install
 composer install -d tools/rector
 ```
 
+The repository root contains the package source, tests, and all primary project configuration files. There is no generated documentation site to update separately, so public behavior changes should be reflected directly in [README.md](README.md) and any affected inline examples.
+
 ## Branches And Commits
 
 Use a short, descriptive branch name. Examples:
@@ -65,6 +67,7 @@ Notes:
 - `composer analyze` runs PHPStan using [phpstan.neon](phpstan.neon).
 - `composer format:check` runs Pint in check mode.
 - `composer refactor:check` requires `tools/rector` dependencies to be installed first.
+- `composer fix` runs Rector, PHPStan, and Pint in sequence. It is useful before opening a pull request, but it does not replace targeted test coverage for behavior changes.
 
 ## Pull Requests
 
@@ -76,6 +79,7 @@ When opening a pull request:
 - Add or update tests for behavior changes.
 - Update documentation when public behavior or examples change.
 - Avoid mixing unrelated refactors with functional changes.
+- Keep examples aligned with the current API, especially `Container::scope()` behavior and `Dependency` usage.
 
 All changes should go through pull request review before merging.
 
diff --git a/README.md b/README.md
index 0b1aad3..94734eb 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,18 @@
-<p>
-    <img height="45" src="docs/logo.png" alt="Logo">
-</p>
-
 [![CI](https://github.com/utopia-php/di/actions/workflows/ci.yml/badge.svg)](https://github.com/utopia-php/di/actions/workflows/ci.yml)
 ![Total Downloads](https://img.shields.io/packagist/dt/utopia-php/di.svg)
 [![Discord](https://img.shields.io/discord/564160730845151244?label=discord)](https://discord.gg/GSeTUeA)
 
-Utopia DI is a small PSR-11 compatible dependency injection container with parent-child scopes. It is designed to stay simple while still covering the dependency lifecycle used across the Utopia libraries. This library is maintained by the [Appwrite team](https://appwrite.io).
+Utopia DI is a minimal [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible dependency injection container with parent-child scopes. It is designed to stay small while covering the dependency lifecycle used across the Utopia libraries. This library is maintained by the [Appwrite team](https://appwrite.io).
+
+Although this library is part of the Utopia project, it is lightweight and works as a standalone package in any PHP codebase.
+
+## Features
 
-Although this library is part of the Utopia Framework project it is dependency free, and can be used as standalone with any other PHP project or framework.
+- PSR-11 compatible container interface
+- Lazy factory execution with per-container result caching
+- Child scopes that inherit parent definitions
+- Local overrides inside a child scope without mutating the parent
+- `Dependency` helper for name-based injection into callbacks
 
 ## Getting Started
 
@@ -46,9 +50,9 @@ $di->set(
 $john = $di->get('john');
 ```
 
-For `Dependency` factories, the `injections` array is matched to callback parameter names, so the array order does not need to mirror the callback signature.
+For `Dependency` factories, the `injections` array is matched to callback parameter names. The array order does not need to match the callback signature.
 
-You can still register plain factories directly when you want access to the container instance.
+You can also register plain factories directly when you want full access to the container instance.
 
 ```php
 $di->set(
@@ -72,7 +76,11 @@ $request->set(
 );
 ```
 
-Factories are resolved once per container instance. A child scope behaves in two distinct ways:
+## Resolution And Scopes
+
+Factories are resolved once per container instance. Resolved values, including `null`, are cached after the first successful lookup.
+
+A child scope behaves in two distinct ways:
 
 - If the child does not define a key, it falls back to the parent and reuses the parent's resolved value.
 - If the child defines the same key locally, it resolves and caches its own value without changing the parent.
@@ -102,27 +110,49 @@ $child->get('requestId'); // "request-2" (child now uses its own local definitio
 $di->get('requestId'); // "request-1" (parent is unchanged)
 ```
 
+## Error Behavior
+
+- `get()` throws `Utopia\DI\Exceptions\NotFoundException` when a dependency does not exist in the current container or any parent scope.
+- Factory failures are wrapped in `Utopia\DI\Exceptions\ContainerException`.
+- Circular dependency resolution also throws `Utopia\DI\Exceptions\ContainerException`.
+
 ## System Requirements
 
 Utopia DI requires PHP 8.2 or later. We recommend using the latest PHP version whenever possible.
 
-## More from Utopia
+## Development
+
+Install dependencies and run the local checks:
 
-Our ecosystem supports other thin PHP projects aiming to extend the core PHP Utopia libraries.
+```bash
+composer install
+composer test
+composer analyze
+composer format:check
+composer refactor:check
+```
+
+`composer refactor:check` requires Rector dependencies from `tools/rector`:
+
+```bash
+composer install -d tools/rector
+```
+
+## More from Utopia
 
-Each project is focused on solving a single, very simple problem and you can use composer to include any of them in your next project.
+Our ecosystem contains small PHP packages focused on solving a single problem well.
 
-You can find all libraries in [GitHub Utopia organization](https://github.com/utopia-php).
+You can browse the wider set of libraries in the [Utopia GitHub organization](https://github.com/utopia-php).
 
 ## Contributing
 
-All code contributions - including those of people having commit access - must go through a pull request and approved by a core developer before being merged. This is to ensure proper review of all the code.
+All code contributions, including those from maintainers, go through pull request review before merging.
 
-Fork the project, create a feature branch, and send us a pull request.
+Fork the project, create a feature branch from `main`, and open a pull request.
 
-You can refer to the [Contributing Guide](https://github.com/utopia-php/di/blob/master/CONTRIBUTING.md) for more info.
+See the [Contributing Guide](CONTRIBUTING.md) for the expected workflow and local checks.
 
-For security issues, please email security@appwrite.io instead of posting a public issue in GitHub.
+For security issues, email `security@appwrite.io` instead of opening a public issue.
 
 ## Copyright and license
 
diff --git a/composer.json b/composer.json
index 8d1730a..d1f9ccd 100644
--- a/composer.json
+++ b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "utopia-php/di",
-    "description": "A simple and lite library for managing dependency injections",
+    "description": "Minimal PSR-11 dependency injection container with scoped child containers",
     "type": "library",
     "keywords": [
         "php",