📝 clarify async build config consumers

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

@@ -2,8 +2,8 @@
 name: async-logger-build-config-type
 group: api
 category: async
-update-time: 20260613
+update-time: 20260614
-description: Public async build config alias combining the base logger config and async runtime config.
+description: Public async build config alias combining the base logger config and async runtime config for both the general async builder path and the specialized text-console builder path.
 key-word:
     - async
     - build
@@ -13,7 +13,7 @@ key-word:
 
 ## Async-logger-build-config-type
 
-`AsyncLoggerBuildConfig` is the public config object that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. It is a direct alias to the build-config model used by async builder APIs, parsers, and serializers.
+`AsyncLoggerBuildConfig` is the public config object that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. It is a direct alias to the build-config model used by async builder APIs, parsers, and serializers, even though the available builders consume different parts of the embedded sync config.
 
 ### Interface
 
@@ -33,6 +33,8 @@ Detailed rules explaining key parameters and behaviors
 - The current fields are `logger : LoggerConfig` and `async_config : AsyncLoggerConfig`.
 - `AsyncLoggerBuildConfig::new(...)` constructs this type as the main handoff object for async build flows.
 - `build_async_logger(...)`, `build_async_text_logger(...)`, `parse_async_logger_build_config_text(...)`, `async_logger_build_config_to_json(...)`, and `stringify_async_logger_build_config(...)` all consume or produce this same public shape.
+- `build_async_logger(...)` consumes the full sync build path by calling `build_logger(config.logger)` first, so `LoggerConfig.sink`, `LoggerConfig.queue`, and the resulting runtime sink behavior all participate before the async layer is added.
+- `build_async_text_logger(...)` is narrower: it builds a text console sink directly from `config.logger.sink.text_formatter` and the top-level `min_level`, `target`, and `timestamp` fields, without applying `LoggerConfig.queue`.
 
 ### How to Use
 
@@ -50,6 +52,8 @@ let config : AsyncLoggerBuildConfig = AsyncLoggerBuildConfig::new(
 
 In this example, both layers of logger setup are kept in one typed value.
 
+And downstream code can still choose between the full sync-first builder path and the narrower text-console builder path.
+
 #### When Need To Export Or Inspect The Full Build Shape
 
 When application code should inspect the combined async build configuration before constructing the logger:
@@ -67,8 +71,14 @@ e.g.:
 
 - If only async runtime policy is needed and the base sync logger config is irrelevant, this type may be broader than necessary and `AsyncLoggerConfig` is the smaller fit.
 
+- If callers expect every `LoggerConfig` field to affect every async builder in the same way, that assumption is too broad: the text-specific builder intentionally ignores the optional sync queue layer.
+
 ### Notes
 
 1. Use `AsyncLoggerBuildConfig::new(...)` when one object should carry both sync and async logger setup.
 
 2. Use `parse_async_logger_build_config_text(...)` when the same shape should come from JSON text instead of handwritten code.
+
+3. Pick `build_async_logger(...)` when the full synchronous config path, including `LoggerConfig.queue`, should be preserved before async wrapping.
+
+4. Pick `build_async_text_logger(...)` when the goal is specifically a concrete text console sink and only the selected text-oriented `LoggerConfig` fields should apply.

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

@@ -2,8 +2,8 @@
 name: parse-async-logger-build-config-text
 group: api
 category: async
-update-time: 20260512
+update-time: 20260614
-description: Parse combined sync logger and async runtime JSON into a typed async build configuration.
+description: Parse combined sync logger and async runtime JSON into a typed async build configuration that can feed either the full async builder path or the specialized text-console builder path.
 key-word:
     - async
     - parse
@@ -27,7 +27,7 @@ pub fn parse_async_logger_build_config_text(input : String) -> AsyncLoggerBuildC
 
 #### output
 
-- `AsyncLoggerBuildConfig` - Typed build config ready for `build_async_logger(...)` or `build_async_text_logger(...)`.
+- `AsyncLoggerBuildConfig` - Typed build config ready for `build_async_logger(...)` or `build_async_text_logger(...)`, with the same parsed shape feeding two distinct builder paths.
 
 ### Explanation
 
@@ -37,6 +37,8 @@ Detailed rules explaining key parameters and behaviors
 - `logger` reuses the same synchronous config schema parsed by `parse_logger_config_text(...)`.
 - `async_config` is parsed through `parse_async_logger_config_text(...)`.
 - This API separates validation from actual async runtime construction.
+- When the parsed config is later passed to `build_async_logger(...)`, the embedded `logger` section goes through the normal sync builder path first, including optional `LoggerConfig.queue` handling.
+- When the same parsed config is passed to `build_async_text_logger(...)`, only `logger.sink.text_formatter` plus the top-level `min_level`, `target`, and `timestamp` fields are consumed directly, so the sync queue layer is not applied.
 
 ### How to Use
 
@@ -54,6 +56,20 @@ let logger = build_async_logger(config)
 
 In this example, parsing and runtime construction remain separate and testable.
 
+And the later builder choice determines whether the parsed sync queue settings participate in construction.
+
+#### When Need Parsed Async Text Console Setup
+
+When JSON should drive async text-console output without the broader runtime sink wrapper:
+```moonbit
+let config = parse_async_logger_build_config_text(raw) catch {
+  err => return
+}
+let logger = build_async_text_logger(config)
+```
+
+In this example, the same parsed config object is reused, but the text-specific builder only applies the selected text-oriented logger fields.
+
 #### When Need To Inspect Async Build Config Before Use
 
 When config should be validated or reviewed before build:
@@ -73,9 +89,15 @@ e.g.:
 
 - If either `logger` or `async_config` contains invalid schema values, parsing fails through the underlying config parsers.
 
+- Successful parsing does not guarantee that every parsed `LoggerConfig` field will matter equally to every async builder; that depends on the chosen builder path.
+
 ### Notes
 
 1. Use this API when async build config is stored as JSON.
 
 2. Use `AsyncLoggerBuildConfig::new(...)` when assembling config directly in code.
 
+3. Use `build_async_logger(...)` after parsing when the full sync config path should be preserved before async wrapping.
+
+4. Use `build_async_text_logger(...)` after parsing when callers specifically want config-driven text console output with a concrete `FormattedConsoleSink`.
+