feat(docs): improve lifecycle management and DI guides

- Updated lifecycle management guide to include `ILambdaLifecycleContext` usage and DI patterns.
- Added examples for direct DI, AWS metadata access, state sharing, and keyed services in OnInit handlers.
- Enhanced dependency injection guide with source-generated DI support for OnInit and OnShutdown.
- Expanded core concepts with lifecycle context access patterns and practical usage scenarios.

Author: j-d-ha

docs/getting-started/core-concepts.md

@@ -85,6 +85,17 @@ lambda.OnShutdown(async (
 });
 ```
 
+### Lifecycle Context Access
+
+Both OnInit and OnShutdown handlers support rich dependency injection patterns:
+
+- **Inject services directly**: `(ICache cache, ILogger logger, CancellationToken ct)` – Recommended for most scenarios
+- **Access AWS metadata**: `(ILambdaLifecycleContext context)` – When you need environment information like function name, region, memory size, or initialization type
+- **Combine both**: `(ILambdaLifecycleContext context, ICache cache)` – Mix context access with direct service injection
+- **Use keyed services**: `([FromKeyedServices("key")] IService service)` – Resolve services registered with specific keys
+
+The `ILambdaLifecycleContext` interface provides AWS environment metadata, a `Properties` dictionary for sharing state between handlers, and access to the scoped `ServiceProvider`. See [Lifecycle Management](../guides/lifecycle-management.md) for detailed patterns and examples.
+
 ### Lifecycle Timeline
 
 ```mermaid

docs/guides/dependency-injection.md

@@ -74,23 +74,63 @@ If your handler doesn't need the Lambda payload, omit the `[FromEvent]` paramete
       remaining time when creating the token.
     - Always pass it down to outbound SDK calls and database queries so you can stop work cleanly.
 
-## Middleware and Lifecycle Hooks
+## Middleware and Lifecycle Hooks: Source-Generated DI
 
 - Middleware receives the invocation scope via the `ILambdaHostContext` argument. Resolve services with
   `context.ServiceProvider` or create reusable middleware classes with constructor injection.
-- `OnInit` and `OnShutdown` handlers run outside the normal invocation scope but each one executes
-  inside its own scoped service provider so you can warm caches, seed connections, or flush telemetry
-  without leaking per-invocation services.
+- `OnInit` and `OnShutdown` handlers now use the same source-generated dependency injection as your main
+  handlers. Each executes inside its own scoped service provider so you can warm caches, seed connections,
+  or flush telemetry without leaking per-invocation services.
 
-```csharp title="OnInit"
-lambda.OnInit(async (services, ct) =>
+OnInit and OnShutdown handlers support multiple dependency injection patterns:
+
+```csharp title="Pattern 1: Direct DI (Recommended)"
+lambda.OnInit(async (ICache cache, ILogger<Program> logger, CancellationToken ct) =>
 {
-    var cache = services.GetRequiredService<ICache>();
+    logger.LogInformation("Warming cache during cold start");
     await cache.WarmUpAsync(ct);
     return true;
 });
 ```
 
+Each handler runs in its own scoped service provider, so you can safely resolve scoped services even
+outside the invocation pipeline.
+
+```csharp title="Pattern 2: Using ILambdaLifecycleContext"
+lambda.OnInit(async (ILambdaLifecycleContext context, ICache cache) =>
+{
+    var logger = context.ServiceProvider.GetRequiredService<ILogger<Program>>();
+    logger.LogInformation(
+        "Init type: {Type}, Function: {Name}, Memory: {MB}MB",
+        context.InitializationType,
+        context.FunctionName,
+        context.FunctionMemorySize
+    );
+
+    await cache.WarmUpAsync(context.CancellationToken);
+    return true;
+});
+```
+
+Use `ILambdaLifecycleContext` when you need AWS environment metadata (region, function name, memory size,
+initialization type) or want to share data between handlers via the `Properties` dictionary.
+
+```csharp title="Pattern 3: Keyed Services"
+builder.Services.AddKeyedSingleton<ICache, RedisCache>("redis");
+builder.Services.AddKeyedSingleton<ICache, MemoryCache>("memory");
+
+lambda.OnInit(async (
+    [FromKeyedServices("redis")] ICache primaryCache,
+    [FromKeyedServices("memory")] ICache fallbackCache,
+    CancellationToken ct
+) =>
+{
+    await primaryCache.WarmUpAsync(ct);
+    await fallbackCache.WarmUpAsync(ct);
+    return true;
+});
+```
+
 ## Configuration and Options
 
 Use the standard options pattern for configuration:

docs/guides/lifecycle-management.md

@@ -132,22 +132,112 @@ Both handlers are awaited simultaneously. Keep shutdown work small—only the re
 
 OnInit and OnShutdown handlers support the same source-generated dependency injection experience as middleware and handlers:
 
-- Request only what you need. The generated delegate resolves typed parameters (services, keyed services, `ILambdaHostContext`, `CancellationToken`, etc.).
+- Request only what you need. The generated delegate resolves typed parameters (services, keyed services, `ILambdaLifecycleContext`, `CancellationToken`, etc.).
 - `MinimalLambda` creates a new `IServiceScope` for every handler invocation, ensuring scoped services (database units of work, caches) are isolated even though you are outside the invocation pipeline.
-- The `IServiceProvider` parameter gives you direct access to the scope for manual resolution when needed.
+- Inject `ILambdaLifecycleContext` when you need AWS environment metadata or want to share state via the `Properties` dictionary. For simple scenarios, inject services directly.
+
+```csharp title="Program.cs - Keyed Services"
+builder.Services.AddKeyedSingleton<IMyClient, PrimaryClient>("primary");
+builder.Services.AddKeyedSingleton<IMyClient, SecondaryClient>("secondary");
 
-```csharp title="Program.cs"
 lambda.OnInit(async (
-    IServiceProvider scope,
-    KeyedService<MyClient>("primary"),
+    [FromKeyedServices("primary")] IMyClient primaryClient,
+    [FromKeyedServices("secondary")] IMyClient secondaryClient,
     CancellationToken ct
 ) =>
 {
-    await MyWarmupAsync(scope, MyClient, ct);
+    await primaryClient.WarmupAsync(ct);
+    await secondaryClient.WarmupAsync(ct);
+    return true;
+});
+```
+
+## Accessing AWS Environment Information
+
+When you need AWS environment metadata during initialization or shutdown, inject `ILambdaLifecycleContext`. This interface provides rich context information about the Lambda execution environment beyond what's available in the standard invocation pipeline.
+
+### Using ILambdaLifecycleContext
+
+```csharp title="Program.cs - AWS Environment Metadata"
+lambda.OnInit(async (ILambdaLifecycleContext context, ILogger<Program> logger) =>
+{
+    logger.LogInformation(
+        "Initializing {FunctionName} v{Version} in {Region}",
+        context.FunctionName,
+        context.FunctionVersion,
+        context.Region
+    );
+
+    logger.LogInformation(
+        "Memory: {Memory}MB, Init type: {InitType}, Elapsed: {Elapsed}ms",
+        context.FunctionMemorySize,
+        context.InitializationType,
+        context.ElapsedTime.TotalMilliseconds
+    );
+
     return true;
 });
 ```
 
+### Sharing State via Properties Dictionary
+
+The `Properties` dictionary lets you share data between OnInit handlers or pass information from initialization to your invocation handlers.
+
+```csharp title="Program.cs - State Sharing"
+lambda.OnInit(async (ILambdaLifecycleContext context) =>
+{
+    var initStartTime = DateTimeOffset.UtcNow;
+    context.Properties["InitStartTime"] = initStartTime;
+    context.Properties["EnvironmentType"] = context.InitializationType;
+
+    return true;
+});
+
+lambda.OnInit(async (ILambdaLifecycleContext context, ILogger<Program> logger) =>
+{
+    if (context.Properties.TryGetValue("InitStartTime", out var startTime))
+    {
+        logger.LogInformation("First handler started at {Time}", startTime);
+    }
+
+    return true;
+});
+```
+
+The `Properties` dictionary is backed by a thread-safe `ConcurrentDictionary<string, object?>` and is shared across all OnInit handlers. Properties set during OnInit are also available to invocation handlers via `ILambdaHostContext.Properties`.
+
+### Available Context Properties
+
+`ILambdaLifecycleContext` exposes the following properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `CancellationToken` | `CancellationToken` | Signals cancellation when `InitTimeout` (OnInit) or `ShutdownDuration - ShutdownDurationBuffer` (OnShutdown) elapses, or when SIGTERM is received |
+| `ServiceProvider` | `IServiceProvider` | The scoped service container for this handler invocation. Use for manual service resolution when direct injection isn't sufficient |
+| `Properties` | `IDictionary<string, object?>` | Thread-safe dictionary for sharing data between handlers or from OnInit to invocation handlers |
+| `ElapsedTime` | `TimeSpan` | Time elapsed since the Lambda execution environment started |
+| `Region` | `string?` | AWS region where the function is running (from `AWS_REGION` env var) |
+| `ExecutionEnvironment` | `string?` | Runtime identifier like `AWS_Lambda_dotnet8` (from `AWS_EXECUTION_ENV` env var) |
+| `FunctionName` | `string?` | Name of the Lambda function (from `AWS_LAMBDA_FUNCTION_NAME` env var) |
+| `FunctionMemorySize` | `int?` | Memory allocated to the function in MB (from `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` env var) |
+| `FunctionVersion` | `string?` | Version of the function being executed (from `AWS_LAMBDA_FUNCTION_VERSION` env var) |
+| `InitializationType` | `string?` | Type of initialization: `on-demand`, `provisioned-concurrency`, `snap-start`, or `lambda-managed-instances` (from `AWS_LAMBDA_INITIALIZATION_TYPE` env var) |
+| `LogGroupName` | `string?` | CloudWatch Logs group name (from `AWS_LAMBDA_LOG_GROUP_NAME` env var, not available in SnapStart) |
+| `LogStreamName` | `string?` | CloudWatch Logs stream name (from `AWS_LAMBDA_LOG_STREAM_NAME` env var, not available in SnapStart) |
+| `TaskRoot` | `string?` | Path to the Lambda function code (from `LAMBDA_TASK_ROOT` env var) |
+
+All AWS environment properties are nullable because they depend on environment variables set by the Lambda runtime. Most are available during normal execution, but some (like `LogGroupName` and `LogStreamName`) are unavailable in SnapStart functions.
+
+### When to Use ILambdaLifecycleContext
+
+Use `ILambdaLifecycleContext` when you need:
+
+- **AWS environment metadata** – Access region, function name, memory size, or initialization type for logging, metrics, or conditional logic based on the execution environment
+- **State sharing** – Pass data between OnInit handlers or from OnInit to invocation handlers via the `Properties` dictionary
+- **Manual service resolution** – Access `ServiceProvider` directly for advanced scenarios where parameter injection isn't sufficient
+
+For simple dependency injection scenarios, prefer injecting services directly as parameters instead of using `ILambdaLifecycleContext.ServiceProvider`.
+
 ## Configuring Lifecycle Behavior
 
 Use `ConfigureLambdaHostOptions` to shape lifecycle behavior centrally or bind the same settings from configuration: