📝 clarify app async build docs

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

@@ -3,7 +3,7 @@ name: build-application-async-logger
 group: api
 category: facade
 update-time: 20260614
-description: Build the application-facing async logger facade from an AsyncLoggerBuildConfig through the sync-first async builder path.
+description: Build the application-facing runtime-sink async logger alias from an AsyncLoggerBuildConfig through the sync-first async builder path.
 key-word:
     - application
     - async
@@ -13,7 +13,7 @@ key-word:
 
 ## Build-application-async-logger
 
-Build an `ApplicationAsyncLogger` from `AsyncLoggerBuildConfig`. This is the application-facing async facade over `build_async_logger(...)`.
+Build an `ApplicationAsyncLogger` from `AsyncLoggerBuildConfig`. This is the application-facing runtime-sink async alias returned through `build_async_logger(...)`.
 
 ### Interface
 
@@ -35,11 +35,13 @@ pub fn build_application_async_logger(
 
 Detailed rules explaining key parameters and behaviors
 
-- This API delegates to `build_async_logger(...)`.
+- This API delegates to `build_async_logger(...)` directly.
 - That means the embedded `LoggerConfig` is built first through the normal synchronous config path before the outer async layer is applied.
-- The returned logger keeps the standard async lifecycle and state helper surface.
-- Because the result is only the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, it also keeps the same failure/reset and runtime-dependent post-close behavior documented on the underlying runtime-sink async logger.
-- Use this facade when application code wants a dedicated async app-level entry point.
+- Any optional synchronous queue layer and runtime-sink controls chosen by `build_logger(config.logger)` remain active under the returned logger.
+- Because the result is only the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this builder does not hide any async helpers or introduce a wrapper layer.
+- The returned logger keeps the full async lifecycle and state helper surface directly, including helpers such as `run()`, `shutdown()`, `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, and `last_error()`.
+- It also keeps the same failure/reset and runtime-dependent post-close behavior documented on the underlying runtime-sink async logger.
+- Use this alias-oriented builder when application code wants the standard runtime-sink async shape without narrowing the public surface.
 
 ### How to Use
 
@@ -61,6 +63,17 @@ In this example, the app-facing async facade is built directly from typed config
 
 And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger.
 
+#### When Need Async State Helpers Immediately After App Construction
+
+When application code should keep the ordinary async helper surface directly:
+```moonbit
+let logger = build_application_async_logger(config)
+ignore(logger.pending_count())
+ignore(logger.state())
+```
+
+In this example, the application alias exposes async state helpers directly because no narrowing wrapper is added.
+
 ### Error Case
 
 e.g.:
@@ -75,3 +88,5 @@ e.g.:
 2. Use `parse_and_build_application_async_logger(...)` when starting from JSON text.
 
 3. Use `build_application_text_async_logger(...)` instead when callers should keep the concrete text-console sink type and the direct text-builder path.
+
+4. Use `build_library_async_logger(...)` instead when a library boundary should narrow the exposed async surface.

docs/api/parse-and-build-application-async-logger.md

@@ -3,7 +3,7 @@ name: parse-and-build-application-async-logger
 group: api
 category: facade
 update-time: 20260614
-description: Parse JSON async build config text and build the application-facing async logger facade through the sync-first async builder path.
+description: Parse JSON async build config text and build the application-facing runtime-sink async logger alias through the sync-first async builder path.
 key-word:
     - application
     - async
@@ -13,7 +13,7 @@ key-word:
 
 ## Parse-and-build-application-async-logger
 
-Parse raw JSON async build config text and build an `ApplicationAsyncLogger` in one step. This facade is the application-oriented counterpart to `parse_async_logger_build_config_text(...)` plus `build_application_async_logger(...)`.
+Parse raw JSON async build config text and build an `ApplicationAsyncLogger` in one step. This is the application-oriented counterpart to `parse_async_logger_build_config_text(...)` plus `build_application_async_logger(...)`.
 
 ### Interface
 
@@ -35,10 +35,12 @@ pub fn parse_and_build_application_async_logger(
 
 Detailed rules explaining key parameters and behaviors
 
-- This API parses async build config text first, then builds the async application facade.
+- This API parses async build config text first, then builds the application async logger through `build_application_async_logger(...)`.
 - Both the embedded sync logger config and async queue/runtime config are validated by the parser layer.
 - The embedded `LoggerConfig` is then built through the normal synchronous config path before the outer async layer is applied.
-- The returned logger keeps the normal async lifecycle and state helpers.
+- Any optional synchronous queue layer and runtime-sink controls from the parsed `logger` section remain active under the returned async logger.
+- Because the result is the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this parse-and-build path does not narrow the helper surface.
+- The returned logger keeps the full async lifecycle and state helpers directly.
 
 ### How to Use
 
@@ -57,6 +59,19 @@ In this example, text parsing and async logger construction happen in one facade
 
 And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger.
 
+#### When Need Async State Helpers After JSON-driven App Construction
+
+When application boot should parse JSON text and still keep direct access to async helper APIs:
+```moonbit
+let logger = parse_and_build_application_async_logger(raw) catch {
+  err => return
+}
+ignore(logger.pending_count())
+ignore(logger.state())
+```
+
+In this example, no unwrap step is needed because the application result is an alias, not a narrowing facade.
+
 ### Error Case
 
 e.g.:
@@ -69,3 +84,5 @@ e.g.:
 1. Use this facade when application boot starts from JSON text.
 
 2. Use `build_application_async_logger(...)` when config is already typed as `AsyncLoggerBuildConfig`.
+
+3. Use `parse_and_build_library_async_logger(...)` instead when text-driven construction should narrow the public async surface for a library boundary.