diff --git a/docs/api/logger-warn.md b/docs/api/logger-warn.md
index 771cd3e..5a87b28 100644
--- a/docs/api/logger-warn.md
+++ b/docs/api/logger-warn.md
@@ -37,7 +37,7 @@ Detailed rules explaining key parameters and behaviors
 
 - This helper delegates to `log(Level::Warn, ...)`.
 - Warning records are useful for abnormal but non-fatal conditions.
-- Per-call target override is not exposed here; use `log(...)` when that is required.
+- 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(...)`.
 - All logger wrappers still participate normally in the write path.
 
 ### How to Use
@@ -62,6 +62,10 @@ logger.warn("retry scheduled", fields=[field("attempt", "3")])
 
 In this example, the warning remains easy to filter and inspect later.
 
+And any shared context already carried by the logger still participates through the sink pipeline.
+
+The write still uses the logger's stored target because this shortcut does not take a one-off `target=` override.
+
 ### Error Case
 
 e.g.: