📝 consolidate logger API and async lifecycle guidance

docs/api/async-logger-dropped-count.md

@@ -35,6 +35,10 @@ Detailed rules explaining key parameters and behaviors
 
 - The counter increases when overflow policy discards records.
 - The counter can also increase when `close(clear=true)` or `shutdown(clear=true)` abandons queued records.
+- It can also increase when shutdown fallback logic converts remaining pending records into dropped records during a clear-close path.
+- After a worker failure short-circuits `wait_idle()`, that shutdown-fallback increase is runtime-dependent in the current implementation: native-worker shutdown can convert leftover pending records into additional dropped records, while compatibility shutdown can leave that closed-queue remainder visible in `pending_count()` instead.
+- That also means `dropped_count()` can still stay unchanged even after `is_closed=true` and retained failure state on compatibility-style shutdown paths, because closure there does not necessarily convert the leftover failed backlog into dropped records.
+- Later log attempts against an already closed queue do not add to this counter by themselves.
 - This is a cumulative counter for the lifetime of the logger value.
 - Use this helper when you need a focused loss metric rather than a full `state()` snapshot.
 
@@ -70,6 +74,8 @@ e.g.:
 
 - If callers need to know why records were lost, they must interpret this metric together with overflow policy and shutdown behavior.
 
+- If `wait_idle()` returned early because the worker failed, `dropped_count()` may still stay unchanged on compatibility shutdown paths even though one leftover closed-queue item remains visible in `pending_count()`.
+
 ### Notes
 
 1. This helper reports record loss only; it does not explain the full logger state.