📝 consolidate logger API and async lifecycle guidance

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 the wrapped logger state.
 key-word:
     - library
     - logger
@@ -33,8 +33,13 @@ 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(...)`.
+- The facade also preserves the wrapped logger's target rules on its exposed write methods: `log(..., target=...)` can override the target for one call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derives another logger with `with_target(...)` or `child(...)`.
+- The facade wraps the same underlying `Logger[S]` value rather than copying or rebuilding it.
+- It does not expose the wider `Logger[S]` composition surface or `ConfiguredLogger` runtime helper methods directly.
+- Most facade reshaping helpers keep the same visible sink type, but `with_context_fields(...)` and `bind(...)` intentionally return `LibraryLogger[ContextSink[S]]` because they extend the sink pipeline.
 - Call `to_logger()` when later code must recover the full underlying `Logger[S]` surface.
+- If `S` is `RuntimeSink`, queued runtime state and file-backed helper behavior also stay on that same wrapped logger value; the facade only hides direct access until `to_logger()` is used.
 
 ### How to Use
 
@@ -49,6 +54,17 @@ let logger : LibraryLogger[ConsoleSink] = LibraryLogger::new(console_sink(), tar
 
 In this example, the package boundary exposes the library facade instead of the full logger type.
 
+#### When Need A One-call Target Override Through The Library Facade
+
+When package code should keep the same library-facing sync value but emit one record under a different target:
+```moonbit
+logger.log(Level::Error, "boom", target="lib.audit")
+```
+
+In this example, the emitted record uses `lib.audit` only for that one call.
+
+And later `info(...)`, `warn(...)`, or `error(...)` calls still use the facade's stored target unless code derives another facade first with `with_target(...)` or `child(...)`.
+
 #### When Need To Recover The Full Logger Later
 
 When a library-facing facade should later be adapted back into the ordinary sync logger surface:
@@ -59,6 +75,8 @@ full.info("started")
 
 In this example, the facade can be unwrapped when broader logger operations are needed internally.
 
+And the unwrapped value still carries the same target and sink pipeline that existed behind the library facade.
+
 ### Error Case
 
 e.g.:
@@ -66,8 +84,14 @@ 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()`.
+
+- If callers need direct composition helpers such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`, they must unwrap first 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.
 
 2. Use `Logger[S]` directly when exposing the full sync composition surface is acceptable.
+
+3. Use `to_logger()` when internal code later needs broader composition or runtime-helper access without changing the public facade type.