📝 clarify library logger wrapper docs

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 while preserving sink typing.
+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
@@ -34,7 +34,9 @@ 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 `log(...)`, `info(...)`, `warn(...)`, and `error(...)`.
+- 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.
 
 ### How to Use
@@ -60,6 +62,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.:
@@ -69,8 +73,12 @@ e.g.:
 
 - 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.