📝 document remaining record helpers

docs/api/field-with-value.md

@@ -0,0 +1,76 @@
+---
+name: field-with-value
+group: api
+category: record
+update-time: 20260613
+description: Return a copy of a field with a replaced value while preserving the key.
+key-word:
+    - field
+    - value
+    - transform
+    - public
+---
+
+## Field-with-value
+
+Return a copy of a `Field` with a different `value`. This helper is the narrowest way to rewrite one field value while preserving the existing key.
+
+### Interface
+
+```moonbit
+pub fn Field::with_value(self : Field, value : String) -> Field {}
+```
+
+#### input
+
+- `self : Field` - Base field whose value should be replaced.
+- `value : String` - New value text for the returned field.
+
+#### output
+
+- `Field` - New field value carrying the updated value.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper returns a new field value instead of mutating the original one.
+- Only the `value` part is replaced.
+- The original `key` is preserved exactly.
+- This is useful for redaction, normalization, or tests that need one adjusted field value without rebuilding the key manually.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Redact One Existing Field Value
+
+When the field key should stay the same but the value should be hidden:
+```moonbit
+let user = field("user", "alice")
+let redacted = user.with_value("***")
+```
+
+In this example, the returned field keeps the same key while changing only the visible value.
+
+#### When Need To Rewrite A Field In Test Data
+
+When one field should be adapted without reconstructing the key by hand:
+```moonbit
+let region = field("region", "cn").with_value("eu")
+```
+
+In this example, the helper keeps the transformation local to one field value.
+
+### Error Case
+
+e.g.:
+- If `value` is empty, the returned field is still valid and simply carries an empty string value.
+
+- If the key should also change, constructing a new field with `field(...)` is clearer than chaining this helper.
+
+### Notes
+
+1. Use this helper when the key should stay stable and only the value should change.
+
+2. It is especially useful for redaction-style value updates in tests or adapters.