diff --git a/docs/api/async-logger-with-context-fields.md b/docs/api/async-logger-with-context-fields.md
index aeca02f..864b36b 100644
--- a/docs/api/async-logger-with-context-fields.md
+++ b/docs/api/async-logger-with-context-fields.md
@@ -40,6 +40,7 @@ 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.
 - 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.
 
@@ -76,6 +77,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
@@ -85,3 +88,5 @@ e.g.:
 2. This async variant preserves the visible `AsyncLogger[S]` type while still injecting shared fields.
 
 3. Use a fresh derived logger when one code path needs shared metadata and another should stay unchanged.
+
+4. 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.