📝 consolidate logger API and async lifecycle guidance

docs/api/async-logger-build-config.md

@@ -2,8 +2,8 @@
 name: async-logger-build-config
 group: api
 category: async
-update-time: 20260613
-description: Create the combined sync-and-async build config used by async logger builder APIs.
+update-time: 20260614
+description: Create the combined sync-and-async build config used by async logger builder APIs, whether callers later choose the full sync-first builder path or the specialized text-console builder path.
 key-word:
     - async
     - build
@@ -13,7 +13,7 @@ key-word:
 
 ## Async-logger-build-config
 
-Create an `AsyncLoggerBuildConfig` value that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. This is the constructor used when async builder APIs should receive one typed object carrying both layers of setup.
+Create an `AsyncLoggerBuildConfig` value that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. This is the constructor used when async builder APIs should receive one typed object carrying both layers of setup, even though different builders later consume different parts of the embedded sync config.
 
 ### Interface
 
@@ -26,7 +26,7 @@ pub fn AsyncLoggerBuildConfig::new(
 
 #### input
 
-- `logger : LoggerConfig` - Base synchronous logger config describing the sink, level, target, and related sync logger settings.
+- `logger : LoggerConfig` - Base synchronous logger config describing the sink, level, target, related sync logger settings, and any optional synchronous queue wrapper.
 - `async_config : AsyncLoggerConfig` - Async runtime config describing queue, batching, linger, and flush behavior.
 
 #### output
@@ -40,6 +40,10 @@ Detailed rules explaining key parameters and behaviors
 - Omitting `logger` uses `default_logger_config()`.
 - Omitting `async_config` uses `AsyncLoggerConfig::new()`.
 - The constructor simply packages both config objects into one public build shape.
+- The constructor does not normalize or reinterpret either embedded config beyond those defaults; any normalization has already happened inside the `LoggerConfig` or `AsyncLoggerConfig` values passed in.
+- When passed to `build_async_logger(...)`, the `logger` portion is built first through the normal synchronous config path before the outer async queue layer is applied.
+- When passed to `build_async_text_logger(...)`, the same `logger` portion is consumed more narrowly: `text_formatter`, `min_level`, `target`, and `timestamp` are used directly to build a text console sink, while `LoggerConfig.queue` is not applied.
+- On that text-specific path, `logger.sink.kind` also does not decide the runtime sink shape. `build_async_text_logger(...)` still constructs `FormattedConsoleSink` from `logger.sink.text_formatter` even if the config says `Console`, `JsonConsole`, or `File`.
 - This helper is the main code-side counterpart to `parse_async_logger_build_config_text(...)`.
 
 ### How to Use
@@ -58,6 +62,10 @@ let config = AsyncLoggerBuildConfig::new(
 
 In this example, the builder input keeps both configuration layers in one typed value.
 
+And later code can still decide whether that shared config should flow into the full sync-first builder or the narrower text-console builder.
+
+And if later code chooses `build_async_text_logger(...)`, that builder choice still matters more than `logger.sink.kind` because only the formatter-backed text path is consumed there.
+
 #### When Need Defaulted Async Build Settings
 
 When code only wants the standard combined config shape with few overrides:
@@ -74,8 +82,16 @@ e.g.:
 
 - If callers only need async runtime policy and not the full builder input shape, `AsyncLoggerConfig::new(...)` is the smaller API.
 
+- If callers expect every field inside `LoggerConfig` to affect every async builder equally, that assumption is too broad: `build_async_text_logger(...)` intentionally skips the optional sync queue layer.
+
+- In particular, carrying `logger.sink.kind=File` inside this config does not force the later text-specific builder path to create a file-backed async logger; only `build_async_logger(...)` branches on sink kind.
+
 ### Notes
 
 1. Use this helper when async builder APIs should receive one combined config object.
 
 2. Pair it with `build_async_logger(...)`, `build_async_text_logger(...)`, or `parse_async_logger_build_config_text(...)` depending on whether the source is code or JSON text.
+
+3. Prefer `build_async_logger(...)` after constructing this value when configured sync sink behavior, including `LoggerConfig.queue`, should be preserved before async wrapping.
+
+4. Prefer `build_async_text_logger(...)` after constructing this value when the goal is specifically config-driven text console output with a concrete `FormattedConsoleSink`.