Minor documentation improvements.

Author: ioquatix

context/best-practices.md

@@ -4,7 +4,7 @@ This guide outlines recommended patterns and practices for building robust, main
 
 ## Application Structure
 
-If you are creating an application that runs services, you should define a top level `services.rb` file:
+If you are creating an application that runs services, you should define a top level `services.rb` file that includes all your service configurations. This file serves as the main entry point for your services. If you are specifically working with the Falcon web server, this file is typically called `falcon.rb` for historical reasons.
 
 ### Service Configuration
 

context/service-architecture.md

@@ -13,7 +13,7 @@ This guide explains the key architectural components of `async-service` and how
 
 ## Environment
 
-The {ruby Async::Service::Environment} represents a lazy-evaluated chain of key-value pairs. It handles:
+The {ruby Async::Service::Environment} represents a lazy-evaluated chain of key-value pairs. It handles configuration storage, lazy evaluation of computed values, and composition through module inclusion to create flexible, reusable service configurations.
 
 ### Configuration Storage
 
@@ -82,7 +82,7 @@ end
 
 ## Service
 
-The {ruby Async::Service::Generic} represents the service implementation layer. It handles:
+The {ruby Async::Service::Generic} represents the service implementation layer. It handles the actual business logic of your services, provides access to configuration through environment evaluators, and manages the service lifecycle including startup, execution, and shutdown phases.
 
 ### Business Logic
 
@@ -172,7 +172,7 @@ end
 
 ## Configuration
 
-The {ruby Async::Service::Configuration} represents the top-level orchestration layer. It handles:
+The {ruby Async::Service::Configuration} represents the top-level orchestration layer. It handles service definition and registration, provides service discovery and management capabilities, supports loading configurations from files, and enables introspection of defined services and their settings.
 
 ### Service Definitions
 

guides/service-architecture/readme.md

@@ -13,7 +13,7 @@ This guide explains the key architectural components of `async-service` and how
 
 ## Environment
 
-The {ruby Async::Service::Environment} represents a lazy-evaluated chain of key-value pairs. It handles:
+The {ruby Async::Service::Environment} represents a lazy-evaluated chain of key-value pairs. It handles configuration storage, lazy evaluation of computed values, and composition through module inclusion to create flexible, reusable service configurations.
 
 ### Configuration Storage
 
@@ -82,7 +82,7 @@ end
 
 ## Service
 
-The {ruby Async::Service::Generic} represents the service implementation layer. It handles:
+The {ruby Async::Service::Generic} represents the service implementation layer. It handles the actual business logic of your services, provides access to configuration through environment evaluators, and manages the service lifecycle including startup, execution, and shutdown phases.
 
 ### Business Logic
 
@@ -172,7 +172,7 @@ end
 
 ## Configuration
 
-The {ruby Async::Service::Configuration} represents the top-level orchestration layer. It handles:
+The {ruby Async::Service::Configuration} represents the top-level orchestration layer. It handles service definition and registration, provides service discovery and management capabilities, supports loading configurations from files, and enables introspection of defined services and their settings.
 
 ### Service Definitions