📝 clarify async target override docs

docs/api/async-logger-debug.md

@@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::debug(
 
 Detailed rules explaining key parameters and behaviors
 
-- This helper delegates to `log(Level::Debug, ...)`.
+- This helper delegates to `log(Level::Debug, ..., fields=fields)`.
 - The record is still subject to min-level gating, patching, filtering, and overflow policy.
+- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`.
 - Debug records are useful for development and targeted diagnostics.
 - Use this helper when a named debug call is clearer than a raw `log(...)` call.
 
@@ -80,4 +81,4 @@ e.g.:
 
 1. Prefer this helper when the event is semantically debug-level.
 
-2. Use `log(...)` when the level must be chosen dynamically.
+2. Use `log(...)` when the level must be chosen dynamically or one call needs a target override.

docs/api/async-logger-error.md

@@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::error(
 
 Detailed rules explaining key parameters and behaviors
 
-- This helper delegates to `log(Level::Error, ...)`.
+- This helper delegates to `log(Level::Error, ..., fields=fields)`.
 - The record is still subject to patching, filtering, and overflow policy.
+- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`.
 - Error records represent the highest built-in severity in this logger API.
 - Use this helper when a named error call is clearer than a raw `log(...)` call.
 
@@ -80,4 +81,6 @@ e.g.:
 
 1. Use this helper for high-severity async application failures.
 
-2. Emitting an error record is separate from the logger worker itself entering failure state.
+2. Use `log(...)` instead when an error call needs a one-off target override.
+
+3. Emitting an error record is separate from the logger worker itself entering failure state.

docs/api/async-logger-info.md

@@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::info(
 
 Detailed rules explaining key parameters and behaviors
 
-- This helper delegates to `log(Level::Info, ...)`.
+- This helper delegates to `log(Level::Info, ..., fields=fields)`.
 - The record is still subject to min-level gating, patching, filtering, and overflow policy.
+- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`.
 - Info is often the default operational logging level for async application events.
 - Use this helper when explicit info intent is clearer than a raw `log(...)` call.
 
@@ -80,4 +81,4 @@ e.g.:
 
 1. This is often the most common convenience method for normal async application events.
 
-2. Use `log(...)` when the call site needs a dynamic level or target override.
+2. Use `log(...)` when the call site needs a dynamic level or a one-off target override.

docs/api/async-logger-log.md

@@ -3,7 +3,7 @@ name: async-logger-log
 group: api
 category: async
 update-time: 20260614
-description: Enqueue a record into the async logger with an explicit level, message, optional fields, and optional target override, using the repo's direct async call style.
+description: Enqueue a record into the async logger with an explicit level, message, optional fields, and optional target override.
 key-word:
     - async
     - logger
@@ -13,7 +13,7 @@ key-word:
 
 ## Async-logger-log
 
-Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods.
+Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods and the only built-in async write API that accepts a per-call target override.
 
 ### Interface
 
@@ -44,6 +44,7 @@ pub async fn[S] AsyncLogger::log(
 Detailed rules explaining key parameters and behaviors
 
 - The logger checks `is_enabled(level)` before building a record.
+- If `target` is empty, the logger uses its stored default target. If `target` is non-empty, that value overrides the stored target for this call only.
 - Context fields, patch logic, and filter logic are applied before enqueue.
 - If timestamping is enabled, `@env.now()` is captured before the record enters the queue.
 - Overflow behavior depends on the configured `AsyncOverflowPolicy`.
@@ -65,7 +66,16 @@ logger.log(
 )
 ```
 
-In this example, all per-record inputs are supplied explicitly.
+In this example, the record overrides the logger's stored target only for this call.
+
+#### When Reuse The Stored Async Target
+
+When a call should keep the logger's existing target:
+```moonbit
+logger.log(@bitlogger.Level::Warn, "slow request")
+```
+
+In this example, the logger falls back to its stored target because no `target=` override is provided.
 
 #### When Build Higher-level Async Logging Helpers
 
@@ -89,4 +99,4 @@ e.g.:
 
 1. Use this API when the call site needs full control instead of a fixed severity helper.
 
-2. Prefer `info()`, `warn()`, and the other shortcuts when only the level differs.
+2. Prefer `info()`, `warn()`, and the other shortcuts when only the level differs and no per-call target override is needed.

docs/api/async-logger-trace.md

@@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::trace(
 
 Detailed rules explaining key parameters and behaviors
 
-- This helper delegates to `log(Level::Trace, ...)`.
+- This helper delegates to `log(Level::Trace, ..., fields=fields)`.
 - The record is still subject to min-level gating, patching, filtering, and overflow policy.
+- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`.
 - Trace records are often skipped in production because they are the lowest built-in severity.
 - Use this helper when explicit trace intent is clearer than a raw `log(...)` call.
 
@@ -80,4 +81,6 @@ e.g.:
 
 1. Prefer this helper when trace intent is more readable than `log(Level::Trace, ...)`.
 
-2. Trace-level async logging can increase queue pressure quickly under verbose workloads.
+2. Use `log(...)` instead when one trace call needs a one-off target override.
+
+3. Trace-level async logging can increase queue pressure quickly under verbose workloads.

docs/api/async-logger-warn.md

@@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::warn(
 
 Detailed rules explaining key parameters and behaviors
 
-- This helper delegates to `log(Level::Warn, ...)`.
+- This helper delegates to `log(Level::Warn, ..., fields=fields)`.
 - The record is still subject to min-level gating, patching, filtering, and overflow policy.
+- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`.
 - Warning records are useful for degraded but non-fatal runtime conditions.
 - Use this helper when a named warning call is clearer than a raw `log(...)` call.
 
@@ -80,4 +81,4 @@ e.g.:
 
 1. Use this helper for notable but non-fatal async runtime conditions.
 
-2. Pair warnings with structured fields when operators need quick context.
+2. Use `log(...)` instead when one warning call must override the target without deriving a new logger value.