📝 document file capability and rotation json helpers

docs/api/file-rotation-config-to-json.md

@@ -0,0 +1,75 @@
+---
+name: file-rotation-config-to-json
+group: api
+category: config
+update-time: 20260613
+description: Convert FileRotation into a JSON value for config export and nested sink serialization.
+key-word:
+    - file
+    - rotation
+    - json
+    - public
+---
+
+## File-rotation-config-to-json
+
+Convert `FileRotation` into a `JsonValue`. This helper is the structured export path for file rotation policy when callers need machine-readable config data instead of a runtime policy object.
+
+### Interface
+
+```moonbit
+pub fn file_rotation_config_to_json(config : FileRotation) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : FileRotation` - File rotation config value to export.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the rotation policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `max_bytes` and `max_backups`.
+- Both numeric fields are exported as JSON numbers.
+- This helper serializes the rotation config object itself rather than sink availability, failure counters, or file state.
+- The same JSON shape is reused by `sink_config_to_json(...)`, file sink state export helpers, and larger logger config serialization paths.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Rotation Policy Export
+
+When file rotation settings should be embedded into a larger config payload:
+```moonbit
+let value = file_rotation_config_to_json(file_rotation(1024 * 1024, max_backups=3))
+```
+
+In this example, the rotation policy becomes a reusable JSON value instead of final text.
+
+#### When Need Manual Sink Config Assembly
+
+When code is exporting only the rotation portion of a file-related config flow:
+```moonbit
+let rotation = file_rotation(4096, max_backups=2)
+let rotation_json = file_rotation_config_to_json(rotation)
+```
+
+In this example, callers can carry the nested rotation shape without exporting a full sink config.
+
+### Error Case
+
+e.g.:
+- If callers need a complete sink or logger config snapshot, this helper alone is too narrow and should be paired with `sink_config_to_json(...)` or `logger_config_to_json(...)`.
+
+- If callers need text output rather than a JSON value, they should stringify a larger containing config instead of manually formatting this value.
+
+### Notes
+
+1. Use this helper when downstream code expects `JsonValue` rather than a typed `FileRotation` value.
+
+2. Pair it with `file_rotation(...)` when building rotation policy in code before export.

docs/api/index.md

@@ -112,6 +112,7 @@ BitLogger API navigation.
 - [filter-sink.md](./filter-sink.md)
 - [patch-sink.md](./patch-sink.md)
 - [file-sink.md](./file-sink.md)
+- [native-files-supported.md](./native-files-supported.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)
@@ -152,6 +153,7 @@ BitLogger API navigation.
 
 - [config-error.md](./config-error.md)
 - [sink-kind.md](./sink-kind.md)
+- [file-rotation-config-to-json.md](./file-rotation-config-to-json.md)
 - [queue-config-type.md](./queue-config-type.md)
 - [queue-config.md](./queue-config.md)
 - [queue-config-to-json.md](./queue-config-to-json.md)

docs/api/native-files-supported.md

@@ -0,0 +1,74 @@
+---
+name: native-files-supported
+group: api
+category: sink
+update-time: 20260613
+description: Query whether the current backend provides real host file support for file sink operations.
+key-word:
+    - native
+    - file
+    - support
+    - public
+---
+
+## Native-files-supported
+
+Query whether the current backend provides real file support for `file_sink(...)` and related file runtime operations. This helper is the public capability gate for code that needs to decide whether host file logging is actually available on the current target.
+
+### Interface
+
+```moonbit
+pub fn native_files_supported() -> Bool {}
+```
+
+#### output
+
+- `Bool` - `true` when the active backend provides real file support, otherwise `false`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper is target-sensitive runtime capability detection, not a compile-time type gate.
+- The native backend currently returns `true`.
+- The stub backend used for non-file-capable targets currently returns `false`.
+- File APIs can remain part of the broader portable surface, but callers should use this check before depending on actual file creation, writes, flushes, or reopen behavior.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Safe Cross-target File Logging
+
+When code should enable file output only on targets that really support it:
+```moonbit
+if native_files_supported() {
+  let sink = file_sink("app.log")
+  Logger::new(sink).info("started")
+}
+```
+
+In this example, file logging is activated only when the backend can actually provide it.
+
+#### When Need To Match Runtime Availability Checks
+
+When capability detection should align with file sink health state:
+```moonbit
+let sink = file_sink("app.log")
+inspect(sink.is_available() == native_files_supported(), content="true")
+```
+
+In this example, the public support flag matches the observable file sink availability contract.
+
+### Error Case
+
+e.g.:
+- If this helper returns `false`, callers should not treat file writes, flushes, or reopen operations as available runtime behavior.
+
+- If this helper returns `true`, individual file operations can still fail later because of path, permission, or filesystem state issues.
+
+### Notes
+
+1. Use this helper as the first portability guard around `file_sink(...)`, `file(...)`, and file-runtime control APIs.
+
+2. See [target-verification.md](./target-verification.md) when you need the current local verification boundary for target-sensitive behavior.