📝 Add global logger API docs

docs/api/default-logger.md

@@ -0,0 +1,75 @@
+---
+name: default-logger
+group: api
+category: global
+update-time: 20260512
+description: Create the shared console-backed logger value used by the global logging helpers.
+key-word:
+    - global
+    - logger
+    - default
+    - public
+---
+
+## Default-logger
+
+Create a `Logger[ConsoleSink]` from the current shared default global configuration. This is the logger value used internally by the global helper functions such as `log(...)`, `info(...)`, and `error(...)`.
+
+### Interface
+
+```moonbit
+pub fn default_logger() -> Logger[ConsoleSink] {}
+```
+
+#### output
+
+- `Logger[ConsoleSink]` - Logger built from the shared console sink, current default minimum level, and current default target.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The returned logger is built from `default_console_sink`, `default_min_level_ref`, and `default_target_ref`.
+- Each call reflects the current shared configuration at that moment.
+- The logger writes to the standard console sink path.
+- This helper is useful when you want the same baseline behavior as the global shortcuts but still need the explicit `Logger` object for chaining or inspection.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Start From Global Defaults But Keep A Logger Value
+
+When code wants the default console path with later composition:
+```moonbit
+let logger = default_logger().with_timestamp()
+logger.info("service started")
+```
+
+In this example, the logger starts from global defaults and then gains extra instance-level behavior.
+
+#### When Inspect Current Shared Behavior
+
+When code should branch using the same threshold as global helpers:
+```moonbit
+let logger = default_logger()
+if logger.is_enabled(Level::Debug) {
+  logger.debug("debug path active")
+}
+```
+
+In this example, the explicit logger mirrors the same level gate used by global shortcut calls.
+
+### Error Case
+
+e.g.:
+- If the shared default target is empty, the returned logger is still valid and simply uses an empty target.
+
+- Changes made later through `set_default_min_level(...)` or `set_default_target(...)` do not mutate an already-stored logger value.
+
+### Notes
+
+1. This helper returns a normal `Logger`, so further chaining is available.
+
+2. It is the bridge between the simple global API and the explicit typed logger workflow.
+

docs/api/global-debug.md

@@ -0,0 +1,77 @@
+---
+name: global-debug
+group: api
+category: global
+update-time: 20260512
+description: Emit a debug-level record through the shared default logger shortcut.
+key-word:
+    - global
+    - debug
+    - default
+    - public
+---
+
+## Global-debug
+
+Emit a debug-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Debug, ...)`.
+
+### Interface
+
+```moonbit
+pub fn debug(message : String, fields~ : Array[Field] = []) -> Unit {}
+```
+
+#### input
+
+- `message : String` - Debug message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled through the shared default logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `default_logger().debug(...)`.
+- The record uses the current shared minimum level and target configuration.
+- Debug output is typically intended for development and troubleshooting.
+- This helper is best suited to small apps or code paths that intentionally rely on the shared logger.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Simple Global Debug Logging
+
+When code wants quick diagnostics without wiring a logger variable:
+```moonbit
+set_default_min_level(Level::Debug)
+debug("cache refreshed")
+```
+
+In this example, the shared global path starts accepting debug records.
+
+#### When Attach Structured Debug Context
+
+When a debug event should include machine-readable detail:
+```moonbit
+debug("session loaded", fields=[field("user_id", "42")])
+```
+
+In this example, the global shortcut still supports structured fields.
+
+### Error Case
+
+e.g.:
+- If the shared minimum level is above `Debug`, the record is skipped.
+
+- If different modules need distinct targets or sinks, a shared global debug path may be too coarse.
+
+### Notes
+
+1. Prefer explicit loggers once application logging becomes subsystem-specific.
+
+2. Use `set_default_min_level(...)` before expecting global debug output to appear.
+

docs/api/global-error.md

@@ -0,0 +1,76 @@
+---
+name: global-error
+group: api
+category: global
+update-time: 20260512
+description: Emit an error-level record through the shared default logger shortcut.
+key-word:
+    - global
+    - error
+    - default
+    - public
+---
+
+## Global-error
+
+Emit an error-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Error, ...)`.
+
+### Interface
+
+```moonbit
+pub fn error(message : String, fields~ : Array[Field] = []) -> Unit {}
+```
+
+#### input
+
+- `message : String` - Error message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled through the shared default logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `default_logger().error(...)`.
+- It uses the shared console sink, default target, and current threshold configuration.
+- `Error` is the highest built-in severity in the global sync helper set.
+- This helper is useful when a small app wants a direct shared failure-reporting path.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Report A Global Failure Event
+
+When a small application should emit an explicit failure log:
+```moonbit
+error("worker execution failed")
+```
+
+In this example, the shared default logger emits a high-severity error record.
+
+#### When Attach Structured Error Context
+
+When an error event should include machine-readable detail:
+```moonbit
+error("dispatch failed", fields=[field("job_id", "42")])
+```
+
+In this example, the global helper still supports structured fields.
+
+### Error Case
+
+e.g.:
+- If the shared minimum level is above `Error`, the call still returns without writing, though this configuration is unusual.
+
+- If one module should not share the same sink or target policy, the global helper path may be too blunt.
+
+### Notes
+
+1. Use this helper for simple shared error reporting.
+
+2. Explicit `Logger` values are usually better once the application needs richer routing or ownership boundaries.
+

docs/api/global-info.md

@@ -0,0 +1,77 @@
+---
+name: global-info
+group: api
+category: global
+update-time: 20260512
+description: Emit an info-level record through the shared default logger shortcut.
+key-word:
+    - global
+    - info
+    - default
+    - public
+---
+
+## Global-info
+
+Emit an info-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Info, ...)`.
+
+### Interface
+
+```moonbit
+pub fn info(message : String, fields~ : Array[Field] = []) -> Unit {}
+```
+
+#### input
+
+- `message : String` - Informational message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled through the shared default logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `default_logger().info(...)`.
+- It uses the shared console sink and current default target.
+- `Info` is the default global threshold unless changed through `set_default_min_level(...)`.
+- This is the simplest entry point for normal app-level informational events.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Emit Simple Global Application Events
+
+When a small app wants direct lifecycle logging:
+```moonbit
+set_default_target("app")
+info("service started")
+```
+
+In this example, the shared default logger emits an informational record under the `app` target.
+
+#### When Attach Structured Informational Data
+
+When a global info event should include metadata:
+```moonbit
+info("request completed", fields=[field("status", "200")])
+```
+
+In this example, the global helper still supports structured fields.
+
+### Error Case
+
+e.g.:
+- If the shared minimum level is above `Info`, the record is skipped.
+
+- If different components need different targets, shared global info logging may become too broad.
+
+### Notes
+
+1. This is the most common global write helper for small applications or scripts.
+
+2. Prefer explicit loggers when the codebase grows beyond one shared logging path.
+

docs/api/global-log.md

@@ -0,0 +1,77 @@
+---
+name: global-log
+group: api
+category: global
+update-time: 20260512
+description: Emit a record through the shared default logger with an explicit level and optional fields.
+key-word:
+    - global
+    - log
+    - default
+    - public
+---
+
+## Global-log
+
+Emit a record through the shared default logger with an explicit level and message. This is the core global write API behind the global severity-specific shortcuts.
+
+### Interface
+
+```moonbit
+pub fn log(level : Level, message : String, fields~ : Array[Field] = []) -> Unit {}
+```
+
+#### input
+
+- `level : Level` - Severity level for the record.
+- `message : String` - Log message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is emitted through the current shared default logger behavior.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The function calls `default_logger().log(level, message, fields=fields)`.
+- It uses the shared console sink and the current global default threshold and target.
+- Per-call target override is not exposed by this global shortcut.
+- This helper is most useful when convenience matters more than explicit logger ownership.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Simple Global Logging Entry
+
+When application code wants a direct severity-controlled write:
+```moonbit
+log(Level::Info, "service started")
+```
+
+In this example, the shared default logger handles the record without requiring an explicit logger variable.
+
+#### When Attach Structured Metadata Globally
+
+When a global event should still include fields:
+```moonbit
+log(Level::Warn, "retry scheduled", fields=[field("attempt", "2")])
+```
+
+In this example, the global path still supports structured logging data.
+
+### Error Case
+
+e.g.:
+- If the level is below the current shared minimum threshold, the write is skipped.
+
+- If a custom target override is required, the explicit `Logger::log(...)` API is a better fit.
+
+### Notes
+
+1. This API is convenient but intentionally less configurable than an explicit logger value.
+
+2. Prefer explicit loggers when different subsystems need different sink or target behavior.
+

docs/api/global-trace.md

@@ -0,0 +1,77 @@
+---
+name: global-trace
+group: api
+category: global
+update-time: 20260512
+description: Emit a trace-level record through the shared default logger shortcut.
+key-word:
+    - global
+    - trace
+    - default
+    - public
+---
+
+## Global-trace
+
+Emit a trace-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Trace, ...)`.
+
+### Interface
+
+```moonbit
+pub fn trace(message : String, fields~ : Array[Field] = []) -> Unit {}
+```
+
+#### input
+
+- `message : String` - Trace message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled through the shared default logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `default_logger().trace(...)`.
+- Trace is the lowest built-in severity and is commonly disabled unless the shared minimum level is lowered.
+- The shared default target and console sink are used.
+- This helper favors convenience over explicit per-component logger ownership.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Quick Global Trace Output
+
+When a script or small app wants temporary low-level diagnostics:
+```moonbit
+set_default_min_level(Level::Trace)
+trace("entered sync loop")
+```
+
+In this example, the shared global path begins accepting trace records.
+
+#### When Attach Structured Trace Context
+
+When a global trace event should carry fields:
+```moonbit
+trace("cache probe", fields=[field("key", "user:42")])
+```
+
+In this example, the global helper still supports structured metadata.
+
+### Error Case
+
+e.g.:
+- If the shared minimum level is above `Trace`, the record is skipped.
+
+- If you need per-call target control, use an explicit `Logger` instead of this helper.
+
+### Notes
+
+1. Global trace logging is convenient for scripts but easy to overuse in larger systems.
+
+2. This helper always goes through the shared default logger path.
+

docs/api/global-warn.md

@@ -0,0 +1,76 @@
+---
+name: global-warn
+group: api
+category: global
+update-time: 20260512
+description: Emit a warn-level record through the shared default logger shortcut.
+key-word:
+    - global
+    - warn
+    - default
+    - public
+---
+
+## Global-warn
+
+Emit a warn-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Warn, ...)`.
+
+### Interface
+
+```moonbit
+pub fn warn(message : String, fields~ : Array[Field] = []) -> Unit {}
+```
+
+#### input
+
+- `message : String` - Warning message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled through the shared default logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `default_logger().warn(...)`.
+- The shared current threshold and target determine whether and how the record is emitted.
+- Warning logs are suited to degraded or suspicious states that do not necessarily stop execution.
+- This helper offers convenience for a single shared logging path.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Quick Global Warning
+
+When a recoverable issue should be surfaced without creating a logger variable:
+```moonbit
+warn("cache miss ratio increased")
+```
+
+In this example, the shared default logger emits a warning-severity record.
+
+#### When Attach Structured Warning Context
+
+When the warning should include machine-readable detail:
+```moonbit
+warn("retry scheduled", fields=[field("attempt", "3")])
+```
+
+In this example, the global helper still supports structured metadata.
+
+### Error Case
+
+e.g.:
+- If the shared minimum level is above `Warn`, the record is skipped.
+
+- If subsystem-specific routing is needed, a shared global warning path may be too limited.
+
+### Notes
+
+1. Global warnings are convenient for simple apps and scripts.
+
+2. Warning-level global events are often the first candidate for separate monitoring or routing later.
+

docs/api/index.md

@@ -38,6 +38,18 @@ BitLogger API navigation.
 - [logger-warn.md](./logger-warn.md)
 - [logger-error.md](./logger-error.md)
 
+## Global logger helpers
+
+- [set-default-min-level.md](./set-default-min-level.md)
+- [set-default-target.md](./set-default-target.md)
+- [default-logger.md](./default-logger.md)
+- [global-log.md](./global-log.md)
+- [global-trace.md](./global-trace.md)
+- [global-debug.md](./global-debug.md)
+- [global-info.md](./global-info.md)
+- [global-warn.md](./global-warn.md)
+- [global-error.md](./global-error.md)
+
 ## Formatter and fields
 
 - [text-formatter.md](./text-formatter.md)

docs/api/set-default-min-level.md

@@ -0,0 +1,76 @@
+---
+name: set-default-min-level
+group: api
+category: global
+update-time: 20260512
+description: Update the minimum level used by the shared default logger helpers.
+key-word:
+    - global
+    - level
+    - default
+    - public
+---
+
+## Set-default-min-level
+
+Update the minimum level used by the shared default logger returned by `default_logger()` and consumed by the global `log(...)`, `info(...)`, `warn(...)`, and similar helpers.
+
+### Interface
+
+```moonbit
+pub fn set_default_min_level(level : Level) -> Unit {}
+```
+
+#### input
+
+- `level : Level` - New minimum level for the shared default logger configuration.
+
+#### output
+
+- `Unit` - No return value. The stored default threshold is updated for later global calls.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The function updates the internal `Ref[Level]` used by `default_logger()`.
+- It does not mutate any separately stored `Logger` values that were created earlier.
+- Later calls to `default_logger()` and the global logging shortcuts observe the new threshold.
+- This is the main API for adjusting process-wide default severity without building a custom logger variable.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Raise Global Threshold In Production
+
+When verbose logs should be suppressed process-wide:
+```moonbit
+set_default_min_level(Level::Warn)
+```
+
+In this example, later global `info(...)` calls are skipped while `warn(...)` and `error(...)` remain active.
+
+#### When Enable Temporary Debug Visibility
+
+When diagnostics should be turned on for a session:
+```moonbit
+set_default_min_level(Level::Debug)
+debug("cache probe enabled")
+```
+
+In this example, the shared global path starts accepting debug records.
+
+### Error Case
+
+e.g.:
+- If the level is set too high, lower-severity global writes are intentionally skipped.
+
+- Existing custom `Logger` instances keep their own thresholds and are not retroactively changed.
+
+### Notes
+
+1. This API only affects the shared default logger workflow.
+
+2. Prefer explicit logger instances when different subsystems need different thresholds at the same time.
+

docs/api/set-default-target.md

@@ -0,0 +1,77 @@
+---
+name: set-default-target
+group: api
+category: global
+update-time: 20260512
+description: Update the default target used by the shared global logger helpers.
+key-word:
+    - global
+    - target
+    - default
+    - public
+---
+
+## Set-default-target
+
+Update the default target used by the shared default logger returned by `default_logger()` and by the global write helpers such as `info(...)` and `error(...)`.
+
+### Interface
+
+```moonbit
+pub fn set_default_target(target : String) -> Unit {}
+```
+
+#### input
+
+- `target : String` - New default target string for the shared global logger configuration.
+
+#### output
+
+- `Unit` - No return value. The stored default target is updated for later global calls.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The function updates the internal `Ref[String]` used by `default_logger()`.
+- It does not mutate any custom `Logger` values created earlier.
+- Later global writes inherit the new target unless a different explicit logger path is used.
+- This is useful when one application wants the convenience of global helpers while still labeling records consistently.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Label Global Application Logs
+
+When global helper calls should carry one stable target:
+```moonbit
+set_default_target("app")
+info("service started")
+```
+
+In this example, the emitted global record uses `app` as its target.
+
+#### When Re-scope A Temporary Execution Context
+
+When a script or tool should tag its own global output:
+```moonbit
+set_default_target("tool.migration")
+warn("running fallback path")
+```
+
+In this example, later global writes stay grouped under the migration target.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, global writes remain valid and simply omit the target unless another logger path supplies one.
+
+- Previously created custom loggers are unaffected because they do not read the shared default target reference afterward.
+
+### Notes
+
+1. This API is best suited for small apps, scripts, or a single shared logging entry path.
+
+2. Prefer explicit child or per-component loggers when target structure needs to vary across subsystems.
+