docs: clarify safeParse callback errors

docs/api-reference/index.mdx

@@ -54,10 +54,12 @@ Base class for all schema types.
 
 - `SchemaResult<Runtime> safeParse(Object? data, {String? debugName})`: Validates
   `data` and returns a `SchemaResult`. Invalid input and recoverable `Exception`
-  values thrown by validation callbacks become failures. Programmer/runtime
-  `Error` values are rethrown with their original stack trace.
+  values thrown by constraint/refinement callbacks become failures. `Error`
+  values from those callbacks are rethrown with their original stack trace.
+  Codec/transform decoder failures, including `Error` values, become
+  `SchemaTransformError` failures.
 - `Runtime? parse(Object? data, {String? debugName})`: Validates `data` and returns the value; throws `AckException` on failure.
-- `SchemaResult<TOut> safeParseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Parses and maps the validated value to `TOut`.
+- `SchemaResult<TOut> safeParseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Parses and maps the validated value to `TOut`. Mapper failures, including `Error` values, become `SchemaTransformError` failures.
 - `TOut parseAs<TOut extends Object>(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Throwing variant of `safeParseAs`.
 - `SchemaResult<Boundary> safeEncode(Runtime? value, {String? debugName})`: Encodes a runtime value to the boundary representation.
 - `Boundary? encode(Runtime? value, {String? debugName})`: Throwing variant of `safeEncode`.

docs/getting-started/quickstart-tutorial.mdx

@@ -27,8 +27,10 @@ See [Schema Types](../core-concepts/schemas.mdx) and [Validation Rules](../core-
 
 Call `safeParse()` with the data you received — for example
 `jsonDecode(response.body)`. It returns a `SchemaResult` for invalid input and
-for recoverable `Exception` values thrown by validation callbacks.
-Programmer/runtime `Error` values are rethrown with their original stack trace.
+for recoverable `Exception` values thrown by constraint/refinement callbacks.
+`Error` values from those callbacks are rethrown with their original stack
+trace. Codec/transform decoders and `safeParseAs` mappers instead turn thrown
+values, including `Error` values, into `SchemaTransformError` failures.
 
 ```dart
 final result = userSchema.safeParse({'name': 'Alice', 'age': 30});

llms.txt

@@ -174,8 +174,11 @@ AckType generation is intentionally strict:
 - `schema.parse(data)` throws on invalid input
 - `schema.safeParse(data)` returns `SchemaResult<T>`
 - `safeParse` turns invalid input and recoverable `Exception` values from
-  validation/refinement callbacks into contextual failures
-- programmer/runtime `Error` values are rethrown with their original stack trace
+  constraint/refinement callbacks into contextual failures
+- `Error` values from constraint/refinement callbacks are rethrown with their
+  original stack trace
+- codec/transform decoders and `safeParseAs` mappers turn thrown values,
+  including `Error` values, into `SchemaTransformError` failures
 - `SchemaResult<T>.getOrThrow()` returns the validated value or throws `AckException`
 - `.optional()` allows a field to be omitted
 - `.nullable()` allows a present field to hold `null`