📝 consolidate logger API and async lifecycle guidance

docs/api/async-flush-policy.md

@@ -2,8 +2,8 @@
 name: async-flush-policy
 group: api
 category: async
-update-time: 20260613
-description: Public flush policy alias used by AsyncLoggerConfig and async worker flushing.
+update-time: 20260614
+description: Public flush policy alias used by AsyncLoggerConfig, async parser labels, and async worker flushing.
 key-word:
     - async
     - flush
@@ -34,6 +34,9 @@ Detailed rules explaining key parameters and behaviors
 - `AsyncFlushPolicy::Batch` calls the configured flush function after each processed batch.
 - `AsyncFlushPolicy::Shutdown` calls the configured flush function once after the worker loop exits.
 - The current flush policy is also exposed through `AsyncLogger::flush_policy()` and included in `AsyncLoggerState`.
+- The canonical labels `Never`, `Batch`, and `Shutdown` are also the labels emitted by async config and logger-state serializers, so parsing and diagnostics share one public vocabulary.
+- Async config parsing accepts the canonical label `Never` and also the compatibility alias `None`, both mapping to the same public enum variant.
+- `Batch` flushing happens after the worker finishes one drained batch, not after every individual record write.
 
 ### How to Use
 
@@ -62,10 +65,16 @@ In this example, flushing happens when the worker loop exits instead of after ea
 e.g.:
 - If async config text uses unsupported flush policy text, async config parsing raises a failure.
 
+- The parser error path for unsupported flush text is the same `Failure` surface used by the async config utilities.
+
 - If a sink never needs explicit flushing, `Batch` or `Shutdown` can add unnecessary work without changing output.
 
+- If the configured flush callback raises, the worker records failure state and stops instead of silently hiding the error.
+
 ### Notes
 
 1. This policy only affects the async logger path and only matters when the configured sink has a meaningful flush function.
 
 2. `AsyncFlushPolicy::Never` is the default in `AsyncLoggerConfig::new(...)`.
+
+3. Serialized config uses the canonical `Never` label even though the parser also accepts `None`.