📝 align facade overview docs

docs/api/async-logger-type.md

@@ -55,6 +55,7 @@ Detailed rules explaining key parameters and behaviors
 - `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, and `last_error` are mutable runtime refs that power the higher-level lifecycle and diagnostics helpers.
 - The sink type parameter is preserved across async composition, which is why helpers such as `with_target(...)`, `with_context_fields(...)`, `with_filter(...)`, and `with_patch(...)` keep returning `AsyncLogger[S]`.
 - `async_logger(...)` constructs this type as the main asynchronous entry point.
+- This root type is also what sits underneath both async facade families: `ApplicationAsyncLogger` is a direct alias over the runtime-sink line, while `LibraryAsyncLogger[S]` is a narrowing wrapper around an `AsyncLogger[S]` value.
 
 ### How to Use
 
@@ -93,6 +94,8 @@ e.g.:
 
 1. Use `async_logger(...)`, `build_async_logger(...)`, or `build_async_text_logger(...)` when you need a value of this type.
 
-2. Use `ApplicationAsyncLogger` or `LibraryAsyncLogger[S]` when a more intention-specific async wrapper or alias fits the calling boundary better.
+2. Use `ApplicationAsyncLogger` when application code wants the same full async lifecycle and state helper surface under an app-facing alias.
 
-3. Prefer the method helpers such as `state()`, `has_failed()`, `last_error()`, `is_running()`, and `shutdown()` instead of reading these public fields conceptually as if they were a stable manual mutation surface.
+3. Use `LibraryAsyncLogger[S]` when a library boundary should intentionally narrow the public async surface and expose broader lifecycle/state helpers only through `to_async_logger()`.
+
+4. Prefer the method helpers such as `state()`, `has_failed()`, `last_error()`, `is_running()`, and `shutdown()` instead of reading these public fields conceptually as if they were a stable manual mutation surface.

docs/api/configured-logger.md

@@ -33,6 +33,7 @@ Detailed rules explaining key parameters and behaviors
 - It preserves normal logger methods such as `info(...)`, `warn(...)`, `error(...)`, and the other `Logger` APIs.
 - It also exposes configured runtime helpers such as `flush()`, `drain()`, `pending_count()`, `dropped_count()`, and file-specific controls when the runtime sink supports them.
 - Builders such as `build_logger(...)` and `parse_and_build_logger(...)` return this alias as the main sync config-to-runtime result.
+- `ApplicationLogger` is another direct alias-oriented name for this same configured runtime surface, while `LibraryLogger[RuntimeSink]` is the narrowing facade variant that intentionally hides these runtime helpers until `to_logger()` is used.
 
 ### How to Use
 
@@ -68,4 +69,6 @@ e.g.:
 
 1. Use `build_logger(...)` or `parse_and_build_logger(...)` when you need a value of this type.
 
-2. Use `ApplicationLogger` or `LibraryLogger[RuntimeSink]` when a more intention-specific facade name fits the calling code better.
+2. Use `ApplicationLogger` when application code wants the same full configured-runtime helper surface under an app-facing name.
+
+3. Use `LibraryLogger[RuntimeSink]` when a library boundary should intentionally hide configured-runtime helper methods behind a narrower facade.

docs/api/logger.md

@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
 - The current fields are `min_level : Level`, `sink : S`, `target : String`, and `timestamp : Bool`.
 - The sink type parameter is preserved across composition, which is why helpers such as `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, and `with_queue(...)` can return more specific logger shapes.
 - `Logger::new(...)` constructs this type as the main synchronous entry point.
+- This root type is also what sits underneath both facade families: `ApplicationLogger` is a direct alias over the configured `Logger[RuntimeSink]` line, while `LibraryLogger[S]` is a narrowing wrapper around a `Logger[S]` value.
 
 ### How to Use
 
@@ -74,4 +75,8 @@ e.g.:
 
 1. Use `Logger::new(...)` when you need a value of this type in code.
 
-2. Use `ConfiguredLogger`, `ApplicationLogger`, or `LibraryLogger[S]` when a more intention-specific wrapper or alias fits the calling boundary better.
+2. Use `ConfiguredLogger` when config-built runtime helpers should stay directly available on the returned logger value.
+
+3. Use `ApplicationLogger` when application code wants that same configured-runtime surface under an app-facing alias.
+
+4. Use `LibraryLogger[S]` when a library boundary should intentionally narrow the public logger surface and expose broader composition only through `to_logger()`.