📝 clarify library facade runtime scope

docs/api/build-library-logger.md

@@ -2,8 +2,8 @@
 name: build-library-logger
 group: api
 category: facade
-update-time: 20260520
+update-time: 20260613
-description: Build the library-facing sync logger facade from a LoggerConfig.
+description: Build the library-facing sync logger facade from a LoggerConfig and intentionally hide direct runtime helper methods.
 key-word:
     - library
     - facade
@@ -33,8 +33,9 @@ pub fn build_library_logger(config : LoggerConfig) -> LibraryLogger[RuntimeSink]
 
 Detailed rules explaining key parameters and behaviors
 
-- This API builds a configured runtime logger first and then wraps it as `LibraryLogger`.
+- This API builds a configured runtime logger first and then wraps it as `LibraryLogger[RuntimeSink]`.
 - The facade intentionally exposes a smaller logging surface than the full configured runtime logger.
+- Queue metrics, flush and drain helpers, and file runtime controls remain on the underlying `ConfiguredLogger`, not on the returned facade itself.
 - Call `to_logger()` if a caller must recover the underlying full logger object.
 
 ### How to Use
@@ -52,12 +53,23 @@ let logger = build_library_logger(
 
 In this example, the logger is built from config and then narrowed to the library facade.
 
+#### When Need Runtime Helpers After Library-oriented Construction
+
+When config-built runtime queue or file controls are still needed internally:
+```moonbit
+let logger = build_library_logger(config)
+let full = logger.to_logger()
+ignore(full.pending_count())
+```
+
+In this example, the library facade is unwrapped before using configured runtime helper methods.
+
 ### Error Case
 
 e.g.:
 - If backend-specific sink limitations exist, they still apply after the facade is built.
 
-- If code later needs methods outside the library facade, it must unwrap with `to_logger()`.
+- If code later needs queue metrics, flush or drain helpers, or file runtime controls, it must unwrap with `to_logger()`.
 
 ### Notes
 

docs/api/library-logger.md

@@ -3,7 +3,7 @@ name: library-logger
 group: api
 category: facade
 update-time: 20260613
-description: Public library-facing sync logger facade type used to expose a narrower surface than Logger.
+description: Public library-facing sync logger facade type used to expose a narrower surface than Logger while preserving sink typing.
 key-word:
     - library
     - logger
@@ -33,7 +33,8 @@ Detailed rules explaining key parameters and behaviors
 
 - This is a public facade struct, not a type alias.
 - The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter.
-- The facade keeps common library-safe operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, and the main write methods.
+- The facade keeps common library-safe operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, and the main write methods `log(...)`, `info(...)`, `warn(...)`, and `error(...)`.
+- It does not expose the wider `Logger[S]` composition surface or `ConfiguredLogger` runtime helper methods directly.
 - Call `to_logger()` when later code must recover the full underlying `Logger[S]` surface.
 
 ### How to Use
@@ -66,6 +67,8 @@ e.g.:
 
 - Runtime behavior still depends on the wrapped sink `S`, so any sink-specific limitations remain unchanged behind the facade.
 
+- If the wrapped sink type is `RuntimeSink`, queue and file runtime helpers still exist on the underlying logger but are not callable through `LibraryLogger[RuntimeSink]` unless it is unwrapped with `to_logger()`.
+
 ### Notes
 
 1. Use `LibraryLogger::new(...)`, `build_library_logger(...)`, or `parse_and_build_library_logger(...)` when you need a value of this type.

docs/api/parse-and-build-library-logger.md

@@ -2,8 +2,8 @@
 name: parse-and-build-library-logger
 group: api
 category: facade
-update-time: 20260520
+update-time: 20260613
-description: Parse JSON logger config text and build the library-facing sync logger facade.
+description: Parse JSON logger config text and build the library-facing sync logger facade while intentionally hiding direct runtime helper methods.
 key-word:
     - library
     - facade
@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
 
 - This API parses config text, validates it, builds the configured logger, and wraps it as a library facade.
 - The returned facade keeps a narrower surface than the underlying configured logger.
+- Queue metrics, flush and drain helpers, and file runtime controls stay on the underlying `ConfiguredLogger`, not on the returned facade itself.
 - `to_logger()` can be used to recover the underlying full logger object when necessary.
 
 ### How to Use
@@ -54,6 +55,19 @@ let logger = parse_and_build_library_logger(
 
 In this example, parsing and library-facade construction happen in one call.
 
+#### When Need Runtime Helpers After Text-driven Library Bootstrapping
+
+When JSON-driven construction should still allow internal runtime inspection later:
+```moonbit
+let logger = parse_and_build_library_logger(raw) catch {
+  err => return
+}
+let full = logger.to_logger()
+ignore(full.pending_count())
+```
+
+In this example, the caller unwraps the library facade before using configured runtime helper methods.
+
 ### Error Case
 
 e.g.:
@@ -61,6 +75,8 @@ e.g.:
 
 - If the parsed config is invalid, a `ConfigError` is raised before the library facade is returned.
 
+- If callers assume configured runtime helper methods are available directly on the returned facade, they must unwrap first with `to_logger()`.
+
 ### Notes
 
 1. This is the narrow library-oriented parse-and-build sync entry point.