📝 document field and file rotation aliases

docs/api/field-type.md

@@ -0,0 +1,70 @@
+---
+name: field-type
+group: api
+category: record
+update-time: 20260613
+description: Public field alias used for structured key-value metadata attached to records.
+key-word:
+    - field
+    - record
+    - alias
+    - public
+---
+
+## Field-type
+
+`Field` is the public structured metadata item type used on records, logger context, filters, and patch helpers. It is a direct alias to the core record field model that stores one key and one value string.
+
+### Interface
+
+```moonbit
+pub type Field = @core.Field
+```
+
+#### output
+
+- `Field` - Public structured field value containing `key` and `value` text.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a constructor helper by itself.
+- The current fields are `key : String` and `value : String`.
+- `field(...)` and `fields(...)` construct this type as the main public helpers.
+- The same value type is consumed by `Record::new(...)`, `Logger::bind(...)`, write APIs that accept `fields`, field-based predicates, and record patch helpers.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Reusable Metadata Value
+
+When one field should be created once and reused across records or loggers:
+```moonbit
+let service_field : Field = field("service", "billing")
+```
+
+In this example, the metadata stays as a typed reusable value instead of being rebuilt inline each time.
+
+#### When Need To Attach Structured Context To A Record
+
+When code should pass field values into record creation directly:
+```moonbit
+let rec = Record::new(Level::Info, "accepted", fields=[field("user", "alice")])
+```
+
+In this example, the field type becomes part of the record's structured metadata payload.
+
+### Error Case
+
+e.g.:
+- `Field` itself does not have a runtime failure mode.
+
+- Empty keys or values are still stored as-is because the type is plain structured data rather than a validated schema.
+
+### Notes
+
+1. Use `field(...)` when you need a value of this type in code.
+
+2. Use arrays of `Field` when attaching multiple metadata entries to records, loggers, or global emitters.

docs/api/file-rotation-type.md

@@ -0,0 +1,70 @@
+---
+name: file-rotation-type
+group: api
+category: sink
+update-time: 20260613
+description: Public file rotation alias used for native size-based file sink policy data.
+key-word:
+    - file
+    - rotation
+    - alias
+    - public
+---
+
+## File-rotation-type
+
+`FileRotation` is the public file sink rotation policy type used for native size-based log file rollover. It is a direct alias to the sink model that stores the byte limit and retained backup count.
+
+### Interface
+
+```moonbit
+pub type FileRotation = @utils.FileRotation
+```
+
+#### output
+
+- `FileRotation` - Public file rotation policy object containing `max_bytes` and `max_backups`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a file sink or rotation trigger by itself.
+- The current fields are `max_bytes : Int` and `max_backups : Int`.
+- `file_rotation(...)` constructs this type as the main public helper.
+- The same value type is consumed by `file_sink(...)`, `FileSinkPolicy::new(...)`, `SinkConfig`, file runtime inspection APIs, and logger config serialization helpers.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Rotation Policy Value
+
+When rotation settings should be assembled once and reused across file sink setup paths:
+```moonbit
+let rotation : FileRotation = file_rotation(1024 * 1024, max_backups=3)
+```
+
+In this example, the rollover policy remains a typed value instead of being embedded directly in one sink call.
+
+#### When Need To Inspect Or Carry Rotation Policy Data
+
+When code should keep rotation settings as structured policy before applying them:
+```moonbit
+let policy = FileSinkPolicy::new(rotation=Some(file_rotation(4096, max_backups=2)))
+```
+
+In this example, the alias type participates in higher-level file sink policy composition.
+
+### Error Case
+
+e.g.:
+- `FileRotation` itself does not have a runtime failure mode.
+
+- A value of this type can still describe rotation behavior that only takes effect on targets where native file support exists.
+
+### Notes
+
+1. Use `file_rotation(...)` when you need a value of this type in code.
+
+2. Use `native_files_supported()` or the target verification guidance when portability matters across non-native targets.

docs/api/index.md

@@ -60,6 +60,7 @@ BitLogger API navigation.
 ## Formatter and fields
 
 - [field.md](./field.md)
+- [field-type.md](./field-type.md)
 - [field-with-value.md](./field-with-value.md)
 - [record-formatter.md](./record-formatter.md)
 - [color-mode.md](./color-mode.md)
@@ -112,6 +113,7 @@ BitLogger API navigation.
 - [patch-sink.md](./patch-sink.md)
 - [file-sink.md](./file-sink.md)
 - [file-rotation.md](./file-rotation.md)
+- [file-rotation-type.md](./file-rotation-type.md)
 - [file-sink-policy-to-json.md](./file-sink-policy-to-json.md)
 - [file-sink-policy.md](./file-sink-policy.md)
 - [stringify-file-sink-policy.md](./stringify-file-sink-policy.md)