diff --git a/docs/api/async-logger-close.md b/docs/api/async-logger-close.md
new file mode 100644
index 0000000..5853ab9
--- /dev/null
+++ b/docs/api/async-logger-close.md
@@ -0,0 +1,75 @@
+---
+name: async-logger-close
+group: api
+category: async
+update-time: 20260512
+description: Close the async logger queue and optionally clear pending records immediately.
+key-word:
+    - async
+    - logger
+    - lifecycle
+    - public
+---
+
+## Async-logger-close
+
+Close the async logger queue and stop treating the logger as an active enqueue target. This API is the low-level lifecycle close primitive behind shutdown flows.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::close(self : AsyncLogger[S], clear? : Bool = false) -> Unit {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger that should be closed.
+- `clear : Bool` - Whether pending records should be abandoned immediately instead of being left for drain behavior.
+
+#### output
+
+- `Unit` - No return value. The logger lifecycle state is updated in place.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `close(...)` marks the logger as closed immediately.
+- `clear=false` closes the queue without explicitly abandoning pending records in the helper itself.
+- `clear=true` counts pending records as dropped and resets `pending_count` to `0` before closing the queue.
+- This helper does not itself wait for the worker to finish.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Immediate Queue Closure
+
+When teardown should stop normal enqueue activity right away:
+```moonbit
+logger.close()
+```
+
+In this example, the logger enters closed state immediately.
+
+#### When Need To Abandon Backlog Explicitly
+
+When pending records should be discarded during fast shutdown:
+```moonbit
+logger.close(clear=true)
+```
+
+In this example, queued backlog is counted as dropped instead of waiting for further drain.
+
+### Error Case
+
+e.g.:
+- If `clear=true`, pending records are intentionally discarded and contribute to `dropped_count()`.
+
+- If callers need graceful waiting for drain completion, `shutdown()` is usually the better API.
+
+### Notes
+
+1. This is a low-level lifecycle helper; prefer `shutdown()` for normal graceful teardown.
+
+2. Use `clear=true` only when backlog loss is an acceptable shutdown tradeoff.
diff --git a/docs/api/async-logger-dropped-count.md b/docs/api/async-logger-dropped-count.md
new file mode 100644
index 0000000..0d4472f
--- /dev/null
+++ b/docs/api/async-logger-dropped-count.md
@@ -0,0 +1,77 @@
+---
+name: async-logger-dropped-count
+group: api
+category: async
+update-time: 20260512
+description: Read the number of records dropped by the async logger because of overflow or queue clearing.
+key-word:
+    - async
+    - logger
+    - queue
+    - public
+---
+
+## Async-logger-dropped-count
+
+Read the cumulative number of records dropped by an async logger. This metric is useful when overflow policy or forced shutdown behavior may discard queued data.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::dropped_count(self : AsyncLogger[S]) -> Int {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose dropped-record counter should be inspected.
+
+#### output
+
+- `Int` - Number of records dropped so far.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The counter increases when overflow policy discards records.
+- The counter can also increase when `close(clear=true)` or `shutdown(clear=true)` abandons queued records.
+- This is a cumulative counter for the lifetime of the logger value.
+- Use this helper when you need a focused loss metric rather than a full `state()` snapshot.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Detect Loss Under Pressure
+
+When queue overflow may discard records:
+```moonbit
+if logger.dropped_count() > 0 {
+  println("async log loss detected")
+}
+```
+
+In this example, the code checks whether the async logger has already discarded records.
+
+#### When Validate Shutdown Behavior In Tests
+
+When a test intentionally clears the queue:
+```moonbit
+logger.close(clear=true)
+ignore(logger.dropped_count())
+```
+
+In this example, the drop counter helps confirm that abandoned backlog was tracked.
+
+### Error Case
+
+e.g.:
+- If no records have been dropped, the method simply returns `0`.
+
+- If callers need to know why records were lost, they must interpret this metric together with overflow policy and shutdown behavior.
+
+### Notes
+
+1. This helper reports record loss only; it does not explain the full logger state.
+
+2. Pair it with `pending_count()` or `state()` when investigating backlog pressure.
diff --git a/docs/api/async-logger-flush-policy.md b/docs/api/async-logger-flush-policy.md
new file mode 100644
index 0000000..99fcc14
--- /dev/null
+++ b/docs/api/async-logger-flush-policy.md
@@ -0,0 +1,74 @@
+---
+name: async-logger-flush-policy
+group: api
+category: async
+update-time: 20260512
+description: Read the async logger flush policy currently governing batch and shutdown flushing behavior.
+key-word:
+    - async
+    - logger
+    - flush
+    - public
+---
+
+## Async-logger-flush-policy
+
+Read the async logger flush policy. This helper exposes which flush mode currently controls batch and shutdown behavior.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::flush_policy(self : AsyncLogger[S]) -> AsyncFlushPolicy {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose flush policy should be inspected.
+
+#### output
+
+- `AsyncFlushPolicy` - Current flush policy used by the async worker logic.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The returned value reflects the policy captured when the async logger was created.
+- `Batch` causes explicit flush calls after worker batch processing.
+- `Shutdown` causes explicit flush calls at worker shutdown.
+- `Never` leaves flushing entirely to sink behavior or external control.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Inspect Runtime Flush Semantics
+
+When diagnostics should show how the worker flushes:
+```moonbit
+ignore(logger.flush_policy())
+```
+
+In this example, the configured flush mode is exposed directly from the logger.
+
+#### When Export Async Runtime Metadata
+
+When code should include flush behavior in custom state reporting:
+```moonbit
+let flush = logger.flush_policy()
+```
+
+In this example, flush behavior can be surfaced without reading the full snapshot.
+
+### Error Case
+
+e.g.:
+- This helper does not expose a normal runtime error path; it returns the configured policy.
+
+- If callers need the policy together with backlog and failure state, `state()` is usually the better API.
+
+### Notes
+
+1. This helper exposes configuration-driven runtime behavior, not dynamic worker health.
+
+2. Use `state()` when you want flush policy packaged with the rest of async logger diagnostics.
diff --git a/docs/api/async-logger-has-failed.md b/docs/api/async-logger-has-failed.md
new file mode 100644
index 0000000..3a7bdae
--- /dev/null
+++ b/docs/api/async-logger-has-failed.md
@@ -0,0 +1,76 @@
+---
+name: async-logger-has-failed
+group: api
+category: async
+update-time: 20260512
+description: Read whether the async logger worker has encountered a failure during queue drain.
+key-word:
+    - async
+    - logger
+    - failure
+    - public
+---
+
+## Async-logger-has-failed
+
+Read whether the async logger worker has encountered a failure. This helper is a compact health signal for async delivery problems.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::has_failed(self : AsyncLogger[S]) -> Bool {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose failure flag should be inspected.
+
+#### output
+
+- `Bool` - Whether the worker has failed.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `run()` clears previous failure state at startup.
+- If the worker loop raises an error, the logger records that failure and exposes it through this flag.
+- This helper is intentionally compact and should usually be paired with `last_error()` for details.
+- Failure state is about runtime drain execution, not whether records were dropped due to overflow policy.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Fast Failure Signal
+
+When runtime diagnostics should branch on worker health:
+```moonbit
+if logger.has_failed() {
+  println(logger.last_error())
+}
+```
+
+In this example, the code checks failure state first, then reads the error detail.
+
+#### When Inspect Async Runtime State In Tests
+
+When a test needs to confirm that drain execution stayed healthy:
+```moonbit
+ignore(logger.has_failed())
+```
+
+In this example, the helper exposes a simple pass-fail runtime indicator.
+
+### Error Case
+
+e.g.:
+- If `has_failed()` is `false`, queue pressure or dropped records may still exist for non-failure reasons.
+
+- If `has_failed()` is `true`, callers should inspect `last_error()` or `state()` for more context.
+
+### Notes
+
+1. This helper reports worker failure, not general queue stress.
+
+2. Pair it with `last_error()` when you need actionable detail.
diff --git a/docs/api/async-logger-is-closed.md b/docs/api/async-logger-is-closed.md
new file mode 100644
index 0000000..3034e04
--- /dev/null
+++ b/docs/api/async-logger-is-closed.md
@@ -0,0 +1,77 @@
+---
+name: async-logger-is-closed
+group: api
+category: async
+update-time: 20260512
+description: Read whether the async logger has been closed and should no longer accept normal new queue traffic.
+key-word:
+    - async
+    - logger
+    - lifecycle
+    - public
+---
+
+## Async-logger-is-closed
+
+Read whether the async logger has been closed. This helper is useful for lifecycle checks around shutdown and queue finalization.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::is_closed(self : AsyncLogger[S]) -> Bool {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose closure state should be inspected.
+
+#### output
+
+- `Bool` - Whether the logger has already been closed.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `close(...)` sets the closed state immediately.
+- `shutdown(...)` also results in a closed logger by the end of its lifecycle flow.
+- A closed logger should no longer be treated as a normal active enqueue target.
+- This helper reflects lifecycle state only and does not indicate whether the worker is still draining.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Guard Late-stage Logging
+
+When code should avoid treating a logger as fully active during teardown:
+```moonbit
+if logger.is_closed() {
+  println("logger already closed")
+}
+```
+
+In this example, teardown logic can branch on the closure state.
+
+#### When Verify Shutdown Progress
+
+When tests or diagnostics want to inspect lifecycle state:
+```moonbit
+logger.close()
+ignore(logger.is_closed())
+```
+
+In this example, the helper confirms that close state was entered.
+
+### Error Case
+
+e.g.:
+- If `is_closed()` returns `true`, pending records may still exist until drain or clear behavior completes.
+
+- If callers need to know whether the worker is still active, they should also inspect `is_running()`.
+
+### Notes
+
+1. Closed state and running state are related but not identical.
+
+2. Use this helper when lifecycle control matters more than queue counters.
diff --git a/docs/api/async-logger-is-running.md b/docs/api/async-logger-is-running.md
new file mode 100644
index 0000000..4343dc3
--- /dev/null
+++ b/docs/api/async-logger-is-running.md
@@ -0,0 +1,76 @@
+---
+name: async-logger-is-running
+group: api
+category: async
+update-time: 20260512
+description: Read whether the async logger worker is currently running and draining the queue.
+key-word:
+    - async
+    - logger
+    - lifecycle
+    - public
+---
+
+## Async-logger-is-running
+
+Read whether the async logger worker is currently active. This helper is useful for runtime diagnostics and shutdown coordination.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::is_running(self : AsyncLogger[S]) -> Bool {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose worker state should be inspected.
+
+#### output
+
+- `Bool` - Whether the async worker loop is currently running.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `run()` sets the running state while the worker loop is active.
+- The flag is cleared when the worker exits normally or after failure handling finishes.
+- A logger may be closed while still running briefly during final drain or shutdown processing.
+- This helper focuses on worker activity rather than queue size or failure details.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Worker Activity Diagnostics
+
+When runtime output should show whether the worker loop is active:
+```moonbit
+println(logger.is_running().to_string())
+```
+
+In this example, diagnostics can distinguish an idle configured logger from one with an active worker.
+
+#### When Coordinate Shutdown Waiting
+
+When code should poll worker completion explicitly:
+```moonbit
+while logger.is_running() {
+  @async.pause()
+}
+```
+
+In this example, callers watch the worker lifecycle directly.
+
+### Error Case
+
+e.g.:
+- If `is_running()` is `false`, pending records may still exist if the worker was never started or has already failed.
+
+- If callers need a one-shot lifecycle flow, `shutdown()` is usually better than manual polling.
+
+### Notes
+
+1. Use this helper for worker activity checks, not as a complete health signal.
+
+2. Pair it with `has_failed()` or `state()` when diagnosing stalled pipelines.
diff --git a/docs/api/async-logger-last-error.md b/docs/api/async-logger-last-error.md
new file mode 100644
index 0000000..d922e49
--- /dev/null
+++ b/docs/api/async-logger-last-error.md
@@ -0,0 +1,76 @@
+---
+name: async-logger-last-error
+group: api
+category: async
+update-time: 20260512
+description: Read the last error recorded by the async logger worker during runtime failure handling.
+key-word:
+    - async
+    - logger
+    - failure
+    - public
+---
+
+## Async-logger-last-error
+
+Read the last error string recorded by the async logger worker. This helper gives the textual detail behind `has_failed()`.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::last_error(self : AsyncLogger[S]) -> String {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose last worker error should be inspected.
+
+#### output
+
+- `String` - Last recorded worker error message, or an empty string if no error was recorded.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `run()` resets the stored error string when the worker starts.
+- If the worker loop fails, the error text is captured from the raised exception.
+- An empty string normally means no failure has been recorded.
+- This helper reports worker execution errors, not ordinary overflow or backpressure conditions.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Failure Detail In Diagnostics
+
+When a compact error message should be surfaced to operators:
+```moonbit
+if logger.has_failed() {
+  println(logger.last_error())
+}
+```
+
+In this example, the error string is only read when failure is present.
+
+#### When Export Full Async State
+
+When custom diagnostics want to include the last error field directly:
+```moonbit
+let err = logger.last_error()
+```
+
+In this example, the helper provides the textual failure detail without building a full snapshot.
+
+### Error Case
+
+e.g.:
+- If no runtime failure has occurred, the method returns an empty string.
+
+- If callers need broader context than just the error text, they should use `state()`.
+
+### Notes
+
+1. Read this helper together with `has_failed()` when interpreting worker health.
+
+2. The stored value is a diagnostic string, not a typed error object.
diff --git a/docs/api/async-logger-pending-count.md b/docs/api/async-logger-pending-count.md
new file mode 100644
index 0000000..71f5a8a
--- /dev/null
+++ b/docs/api/async-logger-pending-count.md
@@ -0,0 +1,76 @@
+---
+name: async-logger-pending-count
+group: api
+category: async
+update-time: 20260512
+description: Read the current number of queued records that have not yet been drained by the async logger worker.
+key-word:
+    - async
+    - logger
+    - queue
+    - public
+---
+
+## Async-logger-pending-count
+
+Read the current number of queued records that are still waiting to be processed. This API is the most direct backlog metric for an async logger instance.
+
+### Interface
+
+```moonbit
+pub fn[S] AsyncLogger::pending_count(self : AsyncLogger[S]) -> Int {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose current backlog should be inspected.
+
+#### output
+
+- `Int` - Current number of pending records still in the async pipeline.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The count increases when records are accepted into the queue.
+- The count decreases as the worker drains records.
+- This is a point-in-time metric and may change immediately after it is read.
+- Use this helper when a single backlog number is enough and a full `state()` snapshot is unnecessary.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Fast Backlog Check
+
+When code should observe queue pressure directly:
+```moonbit
+let pending = logger.pending_count()
+```
+
+In this example, callers get the current queue backlog without building a full diagnostics snapshot.
+
+#### When Wait For Near-idle Conditions
+
+When operators or tests want to inspect drain progress:
+```moonbit
+if logger.pending_count() == 0 {
+  println("queue idle")
+}
+```
+
+In this example, the queue backlog is checked directly.
+
+### Error Case
+
+e.g.:
+- If the worker is not running, `pending_count()` may stay above `0` until records are drained or cleared.
+
+- If the queue is empty, the method simply returns `0`.
+
+### Notes
+
+1. Use `state()` when you also need dropped counts, failure state, or runtime mode.
+
+2. This helper is useful for lightweight health checks and tests.
diff --git a/docs/api/async-logger-shutdown.md b/docs/api/async-logger-shutdown.md
new file mode 100644
index 0000000..341f2f1
--- /dev/null
+++ b/docs/api/async-logger-shutdown.md
@@ -0,0 +1,75 @@
+---
+name: async-logger-shutdown
+group: api
+category: async
+update-time: 20260512
+description: Gracefully stop an async logger by waiting for idle or clearing queued work, then waiting for the worker to finish.
+key-word:
+    - async
+    - logger
+    - lifecycle
+    - public
+---
+
+## Async-logger-shutdown
+
+Gracefully stop an async logger. This is the main high-level shutdown API for async logging because it coordinates drain behavior, closure, and worker completion.
+
+### Interface
+
+```moonbit
+pub async fn[S] AsyncLogger::shutdown(self : AsyncLogger[S], clear? : Bool = false) -> Unit {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger that should be shut down.
+- `clear : Bool` - Whether pending records should be abandoned immediately instead of waiting for idle first.
+
+#### output
+
+- `Unit` - No return value. The method completes after shutdown coordination finishes.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `clear=false` first waits for idle, then closes the logger.
+- If backlog still remains after waiting, shutdown falls back to `close(clear=true)`.
+- `clear=true` immediately closes and abandons pending records.
+- The method waits until `is_running()` becomes `false` before returning.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Graceful Service Shutdown
+
+When a service should stop logging only after queued records are drained:
+```moonbit
+await logger.shutdown()
+```
+
+In this example, the logger waits for normal drain behavior before final closure.
+
+#### When Need Fast Shutdown Under Pressure
+
+When teardown should prefer speed over preserving backlog:
+```moonbit
+await logger.shutdown(clear=true)
+```
+
+In this example, pending work is abandoned intentionally so shutdown can complete sooner.
+
+### Error Case
+
+e.g.:
+- If `clear=true`, pending records are intentionally dropped rather than drained.
+
+- If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state.
+
+### Notes
+
+1. Prefer this API over raw `close()` in normal application shutdown paths.
+
+2. Choose `clear=true` only when loss of queued records is acceptable.
diff --git a/docs/api/async-logger-wait-idle.md b/docs/api/async-logger-wait-idle.md
new file mode 100644
index 0000000..bbad2d6
--- /dev/null
+++ b/docs/api/async-logger-wait-idle.md
@@ -0,0 +1,75 @@
+---
+name: async-logger-wait-idle
+group: api
+category: async
+update-time: 20260512
+description: Wait until the async logger backlog drains to zero or a worker failure interrupts normal progress.
+key-word:
+    - async
+    - logger
+    - queue
+    - public
+---
+
+## Async-logger-wait-idle
+
+Wait until the async logger backlog drains to zero. This helper is useful when callers want to observe idle state without fully shutting down the logger.
+
+### Interface
+
+```moonbit
+pub async fn[S] AsyncLogger::wait_idle(self : AsyncLogger[S]) -> Unit {}
+```
+
+#### input
+
+- `self : AsyncLogger[S]` - Async logger whose backlog should be waited on.
+
+#### output
+
+- `Unit` - No return value. The method completes when the logger becomes idle or failure prevents normal progress.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The helper keeps yielding while `pending_count() > 0`.
+- If `has_failed()` becomes `true`, waiting stops early instead of looping forever.
+- This API does not close the logger or stop the worker.
+- It is narrower than `shutdown()` and is useful when the logger should continue to be used later.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Drain Barrier Without Shutdown
+
+When code should wait for queued work to flush before continuing:
+```moonbit
+await logger.wait_idle()
+```
+
+In this example, the caller waits for backlog drain but leaves the logger usable afterward.
+
+#### When Need Phase Boundaries In Tests
+
+When a test wants to ensure earlier async logs were processed:
+```moonbit
+await logger.wait_idle()
+println("phase complete")
+```
+
+In this example, the wait acts as a barrier between test phases.
+
+### Error Case
+
+e.g.:
+- If the worker has failed, `wait_idle()` stops waiting even if pending records remain.
+
+- If the worker was never started, pending records may not drain and callers should not expect idle progress automatically.
+
+### Notes
+
+1. Use this helper when you want a drain barrier without closing the logger.
+
+2. Prefer `shutdown()` when lifecycle completion matters more than continued reuse.