feat: add the required tag option and UnmarshalerContext

Assisted-by: GLM 5.3 Flash

docs/API.md

@@ -225,6 +225,11 @@ one declared later wins.
 Unknown keys are ignored by default, landing in an untagged embedded map when
 the struct has one; [Strict decoding](#strict-decoding) rejects them instead.
 
+The tag may carry the `required` option, `toml:"host,required"`: the decode
+fails with `missing required key "host"` when no key of the document resolved
+to the field. The check runs after the table is read, so the other fields
+carry their values whether the required one is present or not.
+
 ### Numeric conversion
 
 The parser produces `int64` for every integer and `float64` for every float.
@@ -314,6 +319,21 @@ automatically, and a nil pointer destination is allocated first. An error
 returned from `UnmarshalTOML` halts the decode and propagates wrapped with the
 key path, for example `addr: unmarshal: not a string`.
 
+### Custom decoding: `UnmarshalerContext`
+
+`UnmarshalerContext` is `Unmarshaler` with the decode's context handed in:
+
+```go
+type UnmarshalerContext interface {
+	UnmarshalTOMLContext(ctx context.Context, data any) error
+}
+```
+
+A type that implements both gets `UnmarshalTOMLContext`, so a long custom
+decode can abort on cancellation instead of running to completion. The
+context a non-cancellable entry point carries is `context.Background`, never
+nil.
+
 ### Custom decoding: `encoding.TextUnmarshaler`
 
 A destination type that implements `encoding.TextUnmarshaler` receives a TOML
@@ -752,7 +772,9 @@ See [Custom encoding](#custom-encoding-marshaler).
 
 ### `type Unmarshaler interface{ UnmarshalTOML(data any) error }`
 
-See [Custom decoding](#custom-decoding-unmarshaler).
+See [Custom decoding](#custom-decoding-unmarshaler). `UnmarshalerContext`
+carries the decode's context through `UnmarshalTOMLContext(ctx, data)` and
+wins when a type implements both.
 
 ### `type Number string`