📝 consolidate logger API and async lifecycle guidance

docs/api/async-logger-with-context-fields.md

@@ -31,7 +31,7 @@ pub fn[S] AsyncLogger::with_context_fields(
 
 #### output
 
-- `AsyncLogger[S]` - A new async logger carrying the shared field set.
+- `AsyncLogger[S]` - A new async logger value carrying the shared field set.
 
 ### Explanation
 
@@ -40,7 +40,10 @@ Detailed rules explaining key parameters and behaviors
 - Context fields are merged during `log(...)` before enqueue.
 - When a log call also passes per-record fields, the context fields are placed before those per-call fields.
 - This API returns a new logger value; it does not mutate the original async logger.
+- The provided `fields` array replaces the previously stored shared field set on the returned async logger; it does not append onto whatever `context_fields` the source logger already had.
 - Unlike synchronous `Logger::with_context_fields(...)`, this async variant stores fields directly on `AsyncLogger` instead of changing the visible sink type.
+- Only the stored `context_fields` value changes. Target, minimum level, timestamp flag, queue configuration, and lifecycle/failure state stay on the same `AsyncLogger[S]` surface.
+- In the current direct async coverage, the original logger keeps its previous `context_fields`, while the derived logger prepends the stored shared fields ahead of per-call fields exactly once when records are built.
 
 ### How to Use
 
@@ -59,6 +62,8 @@ let logger = async_logger(console_sink(), target="billing")
 
 In this example, both fields are attached before each record enters the queue.
 
+And the returned async logger still keeps the same queue-facing API surface as the source logger.
+
 #### When Build Child Async Loggers For Subsystems
 
 When a subsystem has both a target and fixed fields:
@@ -75,6 +80,8 @@ In this example, target composition and field binding stay separate but work tog
 e.g.:
 - If `fields` is empty, the logger remains valid and just adds no extra metadata.
 
+- If a derived async logger already had shared context fields, calling `with_context_fields(...)` again replaces that stored shared field set on the new derived logger rather than stacking both sets together.
+
 - If duplicate field keys are provided, all fields are still emitted; conflict handling is left to the consumer side.
 
 ### Notes
@@ -82,3 +89,9 @@ e.g.:
 1. Use this for stable metadata, not highly dynamic event-specific values.
 
 2. This async variant preserves the visible `AsyncLogger[S]` type while still injecting shared fields.
+
+3. State helpers such as `pending_count()`, `dropped_count()`, `is_closed()`, and `has_failed()` remain available on the returned logger because the visible async logger surface is preserved.
+
+4. Use a fresh derived logger when one code path needs shared metadata and another should stay unchanged.
+
+5. If you need to combine two shared field sets, combine them in the `fields` argument yourself instead of expecting repeated `with_context_fields(...)` calls to accumulate them.