effect 4.0.0-beta.71 → 4.0.0-beta.72

package/dist/Schema.js

@@ -215,7 +215,7 @@ export function declare(is, annotations) {
   return declareConstructor()([], () => (input, ast) => is(input) ? Effect.succeed(input) : Effect.fail(new Issue.InvalidType(ast, Option_.some(input))), annotations);
 }
 /**
- * Widens a schema's type to the fully-parameterized {@link Bottom} interface,
+ * Returns a schema widened to the fully-parameterized {@link Bottom} interface,
  * making all 14 type parameters visible to TypeScript.
  *
  * **Details**
@@ -346,8 +346,8 @@ export function annotateKey(annotations) {
   };
 }
 /**
- * Identity function that widens a value to the full {@link Codec} interface,
- * prompting TypeScript to infer all four type parameters (`T`, `E`, `RD`, `RE`).
+ * Returns a codec widened to the full {@link Codec} interface, prompting
+ * TypeScript to infer all four type parameters (`T`, `E`, `RD`, `RE`).
  *
  * **Details**
  *
@@ -563,7 +563,7 @@ function toBaseStandardJSONSchemaV1(self, target) {
   throw new globalThis.Error(`Unsupported target: ${target}`);
 }
 /**
- * Experimental support for converting a schema to a Standard JSON Schema V1.
+ * Converts a schema to an experimental Standard JSON Schema V1 representation.
  *
  * **Details**
  *
@@ -634,11 +634,15 @@ export const is = Parser.is;
  * Creates an assertion function that throws an error if the input doesn't match
  * the schema.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input at runtime while narrowing the value with a
+ * TypeScript `asserts` predicate.
+ *
  * **Details**
  *
- * This function is useful for runtime type checking with TypeScript's `asserts`
- * type guard. It narrows the type of the input if the assertion succeeds, or
- * throws an error if it fails.
+ * The input is narrowed if the assertion succeeds. If validation fails, the
+ * assertion throws.
  *
  * **Example** (Basic Usage)
  *
@@ -666,9 +670,16 @@ export const is = Parser.is;
 export const asserts = Parser.asserts;
 /**
  * Decodes an `unknown` input against a schema, returning an `Effect` that
- * succeeds with the decoded value or fails with a {@link SchemaError}. Use this
- * when the input type is not statically known. Prefer {@link decodeEffect} when
- * the input is already typed as the schema's `Encoded` type.
+ * succeeds with the decoded value or fails with a {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when decoding input whose type is not statically known.
+ *
+ * **Details**
+ *
+ * Prefer {@link decodeEffect} when the input is already typed as the schema's
+ * `Encoded` type.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -684,8 +695,15 @@ export function decodeUnknownEffect(schema, options) {
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Effect` that succeeds with the decoded value or fails with a
- * {@link SchemaError}. Use this when the input is already typed; for `unknown`
- * input use {@link decodeUnknownEffect}.
+ * {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when the input is already typed as the schema's `Encoded` type.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link decodeUnknownEffect}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -696,9 +714,18 @@ export const decodeEffect = decodeUnknownEffect;
 /**
  * Decodes an `unknown` input against a schema synchronously, returning an
  * `Exit` that is either a `Success` with the decoded value or a `Failure` with
- * a {@link SchemaError}. Only usable with schemas that have no
- * `DecodingServices` requirement. Prefer {@link decodeExit} when the input is
- * already typed as the schema's `Encoded` type.
+ * a {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when the input type is not statically known and decoding should return an
+ * `Exit` instead of failing or throwing.
+ *
+ * **Details**
+ *
+ * Only usable with schemas that have no `DecodingServices` requirement. Prefer
+ * {@link decodeExit} when the input is already typed as the schema's `Encoded`
+ * type.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -714,9 +741,17 @@ export function decodeUnknownExit(schema, options) {
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema
  * synchronously, returning an `Exit` that is either a `Success` with the
- * decoded value or a `Failure` with a {@link SchemaError}. Only usable with
- * schemas that have no `DecodingServices` requirement. For `unknown` input use
- * {@link decodeUnknownExit}.
+ * decoded value or a `Failure` with a {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be decoded into an `Exit` instead of failing or
+ * throwing.
+ *
+ * **Details**
+ *
+ * Only usable with schemas that have no `DecodingServices` requirement. For
+ * `unknown` input use {@link decodeUnknownExit}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -726,10 +761,17 @@ export function decodeUnknownExit(schema, options) {
 export const decodeExit = decodeUnknownExit;
 /**
  * Decodes an `unknown` input against a schema, returning an `Option` that is
- * `Some` with the decoded value on success or `None` on failure. Prefer this
- * over {@link decodeUnknownExit} or {@link decodeUnknownEffect} when you only
- * need to know whether decoding succeeded and don't need error details. For
- * typed input use {@link decodeOption}.
+ * `Some` with the decoded value on success or `None` on failure.
+ *
+ * **When to use**
+ *
+ * Use when the input type is not statically known and you only need to know
+ * whether decoding succeeded.
+ *
+ * **Details**
+ *
+ * Prefer this over {@link decodeUnknownExit} or {@link decodeUnknownEffect}
+ * when you don't need error details. For typed input use {@link decodeOption}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -740,7 +782,15 @@ export const decodeUnknownOption = Parser.decodeUnknownOption;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Option` that is `Some` with the decoded value on success or
- * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ * `None` on failure.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be decoded and only success or failure matters.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link decodeUnknownOption}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -750,8 +800,16 @@ export const decodeUnknownOption = Parser.decodeUnknownOption;
 export const decodeOption = Parser.decodeOption;
 /**
  * Decodes an `unknown` input against a schema, returning a `Result` that
- * succeeds with the decoded value or fails with a schema issue. For typed input
- * use {@link decodeResult}.
+ * succeeds with the decoded value or fails with a schema issue.
+ *
+ * **When to use**
+ *
+ * Use when the input type is not statically known and decoding should return a
+ * `Result` with structured issue data.
+ *
+ * **Details**
+ *
+ * For typed input use {@link decodeResult}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -762,7 +820,16 @@ export const decodeUnknownResult = Parser.decodeUnknownResult;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning a `Result` that succeeds with the decoded value or fails with a
- * schema issue. For `unknown` input use {@link decodeUnknownResult}.
+ * schema issue.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be decoded into a `Result` with structured issue
+ * data.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link decodeUnknownResult}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -772,9 +839,15 @@ export const decodeUnknownResult = Parser.decodeUnknownResult;
 export const decodeResult = Parser.decodeResult;
 /**
  * Decodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the decoded value or rejects with a schema issue. Useful for
- * integrating with Promise-based APIs. For typed input use
- * {@link decodePromise}.
+ * resolves with the decoded value or rejects with a schema issue.
+ *
+ * **When to use**
+ *
+ * Use when integrating unknown input validation with Promise-based APIs.
+ *
+ * **Details**
+ *
+ * For typed input use {@link decodePromise}.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -785,10 +858,15 @@ export const decodeUnknownPromise = Parser.decodeUnknownPromise;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning a `Promise` that resolves with the decoded value or rejects with a
- * schema issue. For `unknown` input use `decodeUnknownPromise`.
+ * schema issue.
+ *
+ * **When to use**
+ *
+ * Use when integrating typed input decoding with Promise-based APIs.
  *
  * **Details**
  *
+ * For `unknown` input use `decodeUnknownPromise`.
  * Options may be provided either when creating the decoder or when applying it;
  * application options override creation options.
  *
@@ -799,11 +877,15 @@ export const decodePromise = Parser.decodePromise;
 /**
  * Decodes an `unknown` input against a schema synchronously, returning the
  * decoded value or throwing an `Error` whose cause contains the schema issue.
- * Use this when you want to validate data at a boundary and treat a schema
- * mismatch as an exception. For typed input use `decodeSync`.
+ *
+ * **When to use**
+ *
+ * Use when validating unknown data at a boundary and treating schema mismatches
+ * as exceptions.
  *
  * **Details**
  *
+ * For typed input use `decodeSync`.
  * Only service-free schemas can be decoded synchronously. For non-throwing
  * alternatives see `decodeUnknownOption`, `decodeUnknownExit`, or
  * `decodeUnknownEffect`. Options may be provided either when creating the
@@ -833,10 +915,16 @@ export const decodeUnknownSync = Parser.decodeUnknownSync;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema
  * synchronously, returning the decoded value or throwing an `Error` whose cause
- * contains the schema issue. For `unknown` input use `decodeUnknownSync`.
+ * contains the schema issue.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be decoded synchronously and schema mismatches
+ * should throw.
  *
  * **Details**
  *
+ * For `unknown` input use `decodeUnknownSync`.
  * Only service-free schemas can be decoded synchronously. Options may be
  * provided either when creating the decoder or when applying it; application
  * options override creation options.
@@ -847,9 +935,16 @@ export const decodeUnknownSync = Parser.decodeUnknownSync;
 export const decodeSync = Parser.decodeSync;
 /**
  * Encodes an `unknown` input against a schema, returning an `Effect` that
- * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
- * when the input type is not statically known. Prefer {@link encodeEffect} when
- * the input is already typed as the schema's `Type`.
+ * succeeds with the encoded value or fails with a {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when encoding input whose type is not statically known.
+ *
+ * **Details**
+ *
+ * Prefer {@link encodeEffect} when the input is already typed as the schema's
+ * `Type`.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -876,8 +971,15 @@ export function encodeUnknownEffect(schema, options) {
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning an
  * `Effect` that succeeds with the encoded value or fails with a
- * {@link SchemaError}. Use this when the input is already typed; for `unknown`
- * input use {@link encodeUnknownEffect}.
+ * {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when the input is already typed as the schema's `Type`.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link encodeUnknownEffect}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -888,9 +990,17 @@ export const encodeEffect = encodeUnknownEffect;
 /**
  * Encodes an `unknown` input against a schema synchronously, returning an
  * `Exit` that is either a `Success` with the encoded value or a `Failure` with
- * a {@link SchemaError}. Only usable with schemas that have no
- * `EncodingServices` requirement. Prefer {@link encodeExit} when the input is
- * already typed as the schema's `Type`.
+ * a {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when the input type is not statically known and encoding should return an
+ * `Exit` instead of failing or throwing.
+ *
+ * **Details**
+ *
+ * Only usable with schemas that have no `EncodingServices` requirement. Prefer
+ * {@link encodeExit} when the input is already typed as the schema's `Type`.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -906,9 +1016,17 @@ export function encodeUnknownExit(schema, options) {
 /**
  * Encodes a typed input (the schema's `Type`) against a schema synchronously,
  * returning an `Exit` that is either a `Success` with the encoded value or a
- * `Failure` with a {@link SchemaError}. Only usable with schemas that have no
- * `EncodingServices` requirement. For `unknown` input use
- * {@link encodeUnknownExit}.
+ * `Failure` with a {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be encoded into an `Exit` instead of failing or
+ * throwing.
+ *
+ * **Details**
+ *
+ * Only usable with schemas that have no `EncodingServices` requirement. For
+ * `unknown` input use {@link encodeUnknownExit}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -918,10 +1036,17 @@ export function encodeUnknownExit(schema, options) {
 export const encodeExit = encodeUnknownExit;
 /**
  * Encodes an `unknown` input against a schema, returning an `Option` that is
- * `Some` with the encoded value on success or `None` on failure. Prefer this
- * over {@link encodeUnknownExit} or {@link encodeUnknownEffect} when you only
- * need to know whether encoding succeeded and don't need error details. For
- * typed input use {@link encodeOption}.
+ * `Some` with the encoded value on success or `None` on failure.
+ *
+ * **When to use**
+ *
+ * Use when the input type is not statically known and you only need to know
+ * whether encoding succeeded.
+ *
+ * **Details**
+ *
+ * Prefer this over {@link encodeUnknownExit} or {@link encodeUnknownEffect}
+ * when you don't need error details. For typed input use {@link encodeOption}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -932,7 +1057,15 @@ export const encodeUnknownOption = Parser.encodeUnknownOption;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning an
  * `Option` that is `Some` with the encoded value on success or `None` on
- * failure. For `unknown` input use {@link encodeUnknownOption}.
+ * failure.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be encoded and only success or failure matters.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link encodeUnknownOption}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -942,8 +1075,16 @@ export const encodeUnknownOption = Parser.encodeUnknownOption;
 export const encodeOption = Parser.encodeOption;
 /**
  * Encodes an `unknown` input against a schema, returning a `Result` that
- * succeeds with the encoded value or fails with a schema issue. For typed input
- * use {@link encodeResult}.
+ * succeeds with the encoded value or fails with a schema issue.
+ *
+ * **When to use**
+ *
+ * Use when the input type is not statically known and encoding should return a
+ * `Result` with structured issue data.
+ *
+ * **Details**
+ *
+ * For typed input use {@link encodeResult}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -954,6 +1095,14 @@ export const encodeUnknownResult = Parser.encodeUnknownResult;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning a
  * `Result` that succeeds with the encoded value or fails with a schema issue.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be encoded into a `Result` with structured issue
+ * data.
+ *
+ * **Details**
+ *
  * For `unknown` input use {@link encodeUnknownResult}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
@@ -964,9 +1113,15 @@ export const encodeUnknownResult = Parser.encodeUnknownResult;
 export const encodeResult = Parser.encodeResult;
 /**
  * Encodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the encoded value or rejects with a schema issue. Useful for
- * integrating with Promise-based APIs. For typed input use
- * {@link encodePromise}.
+ * resolves with the encoded value or rejects with a schema issue.
+ *
+ * **When to use**
+ *
+ * Use when integrating unknown input serialization with Promise-based APIs.
+ *
+ * **Details**
+ *
+ * For typed input use {@link encodePromise}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -977,7 +1132,15 @@ export const encodeUnknownPromise = Parser.encodeUnknownPromise;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema, returning a
  * `Promise` that resolves with the encoded value or rejects with a
- * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ * {@link SchemaError}.
+ *
+ * **When to use**
+ *
+ * Use when integrating typed input serialization with Promise-based APIs.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link encodeUnknownPromise}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -987,9 +1150,16 @@ export const encodeUnknownPromise = Parser.encodeUnknownPromise;
 export const encodePromise = Parser.encodePromise;
 /**
  * Encodes an `unknown` input against a schema synchronously, throwing a
- * {@link SchemaError} on failure. Use this when you want to serialize data at a
- * boundary and treat a schema mismatch as an unrecoverable error. For
- * non-throwing alternatives see {@link encodeUnknownOption},
+ * {@link SchemaError} on failure.
+ *
+ * **When to use**
+ *
+ * Use when serializing unknown data at a boundary and treating schema
+ * mismatches as unrecoverable errors.
+ *
+ * **Details**
+ *
+ * For non-throwing alternatives see {@link encodeUnknownOption},
  * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
  * use {@link encodeSync}.
  * Options may be provided either when creating the encoder or when applying it;
@@ -1001,8 +1171,16 @@ export const encodePromise = Parser.encodePromise;
 export const encodeUnknownSync = Parser.encodeUnknownSync;
 /**
  * Encodes a typed input (the schema's `Type`) against a schema synchronously,
- * throwing a {@link SchemaError} on failure. For `unknown` input use
- * {@link encodeUnknownSync}.
+ * throwing a {@link SchemaError} on failure.
+ *
+ * **When to use**
+ *
+ * Use when typed input should be encoded synchronously and schema mismatches
+ * should throw.
+ *
+ * **Details**
+ *
+ * For `unknown` input use {@link encodeUnknownSync}.
  * Options may be provided either when creating the encoder or when applying it;
  * application options override creation options.
  *
@@ -1055,7 +1233,7 @@ export function asClass(schema) {
   return Object.setPrototypeOf(Class, schema);
 }
 /**
- * Tests if a value is a `Schema`.
+ * Checks whether a value is a `Schema`.
  *
  * @category guards
  * @since 3.10.0
@@ -1089,8 +1267,12 @@ export const optionalKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.option
   schema
 }));
 /**
- * Reverses {@link optionalKey}, returning the inner required schema. Only
- * applicable to schemas already wrapped with `optionalKey`.
+ * Reverses `optionalKey` and returns the inner required schema.
+ *
+ * **When to use**
+ *
+ * Use to remove optional-key wrapping from a schema field that was previously
+ * wrapped with {@link optionalKey}.
  *
  * @category combinators
  * @since 4.0.0
@@ -1127,8 +1309,16 @@ export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
  */
 export const optional = /*#__PURE__*/Struct_.lambda(self => optionalKey(UndefinedOr(self)));
 /**
- * Reverses {@link optional}, returning the inner schema (unwrapping `UndefinedOr`).
- * Only applicable to schemas already wrapped with `optional`.
+ * Reverses `optional` and returns the inner schema.
+ *
+ * **When to use**
+ *
+ * Use to remove optional wrapping from a schema field that was previously
+ * wrapped with {@link optional}.
+ *
+ * **Details**
+ *
+ * This also unwraps the `UndefinedOr` member added by `optional`.
  *
  * @category combinators
  * @since 3.10.0
@@ -1145,8 +1335,12 @@ export const mutableKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.mutable
   schema
 }));
 /**
- * Reverses {@link mutableKey}, returning the inner schema as readonly again.
- * Only applicable to schemas already wrapped with `mutableKey`.
+ * Reverses `mutableKey` and returns the inner readonly schema.
+ *
+ * **When to use**
+ *
+ * Use to remove mutable-key wrapping from a schema field that was previously
+ * wrapped with {@link mutableKey}.
  *
  * @category combinators
  * @since 4.0.0
@@ -1241,8 +1435,17 @@ export function TemplateLiteral(parts) {
   });
 }
 /**
- * Like {@link TemplateLiteral} but decodes the matched string into a readonly tuple of typed values,
- * one element per schema part.
+ * Schema for parsing template literal matches into typed tuple parts.
+ *
+ * **When to use**
+ *
+ * Use to validate a template literal string and decode the matched parts into
+ * typed values.
+ *
+ * **Details**
+ *
+ * Unlike {@link TemplateLiteral}, this schema decodes the matched string into a
+ * readonly tuple with one element per schema part.
  *
  * **Example** (Parse path parameters)
  *
@@ -1463,8 +1666,16 @@ export function Struct(fields) {
   return makeStruct(AST.struct(fields, undefined), fields);
 }
 /**
- * A shortcut for `MyStruct.mapFields(Struct.assign(fields))`. This is useful
- * when you want to add new fields to an existing struct or a union of structs.
+ * Adds fields to a struct schema through a struct-mapping lambda.
+ *
+ * **When to use**
+ *
+ * Use to add the same fields to an existing struct or to every struct member of
+ * a union.
+ *
+ * **Details**
+ *
+ * This is a shortcut for `MyStruct.mapFields(Struct.assign(fields))`.
  *
  * **Example** (Adding fields to a union of structs)
  *
@@ -1949,8 +2160,8 @@ export function suspend(f) {
   return make(new AST.Suspend(() => f().ast));
 }
 /**
- * Pipeable function that attaches one or more filter checks to a schema without
- * changing the TypeScript type.
+ * Attaches one or more filter checks to a schema without changing the
+ * TypeScript type.
  *
  * **Example** (Adding checks to a schema)
  *
@@ -2111,7 +2322,7 @@ export function catchDecoding(f) {
   return catchDecodingWithContext(f);
 }
 /**
- * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
+ * Recovers from a decoding error with a handler that may require Effect services.
  *
  * **When to use**
  *
@@ -2148,7 +2359,7 @@ export function catchEncoding(f) {
   return catchEncodingWithContext(f);
 }
 /**
- * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
+ * Recovers from an encoding error with a handler that may require Effect services.
  *
  * **When to use**
  *
@@ -2458,9 +2669,17 @@ export function tag(literal) {
   return Literal(literal).pipe(withConstructorDefault(Effect.succeed(literal)));
 }
 /**
- * Like {@link tag}, but additionally omits the tag field from the encoded output.
- * Useful when the encoded form (e.g. JSON) does not include the discriminator key,
- * but the decoded type and constructor still need it.
+ * Creates a literal `_tag` schema that is omitted from encoded output.
+ *
+ * **When to use**
+ *
+ * Use to decode data that omits the discriminator field while still constructing
+ * values with a `_tag` for tagged union matching.
+ *
+ * **Details**
+ *
+ * The tag is filled during decoding and construction, like {@link tag}, but is
+ * omitted when encoding.
  *
  * **Example** (Tag omitted during encoding)
  *
@@ -2487,9 +2706,11 @@ export function tagDefaultOmit(literal) {
   }));
 }
 /**
- * A tagged struct is a struct that includes a `_tag` field. This field is used
- * to identify the specific variant of the object, which is especially useful
- * when working with union types.
+ * Creates a struct schema with an automatically populated `_tag` field.
+ *
+ * **When to use**
+ *
+ * Use to define a tagged union case from a literal tag and a set of fields.
  *
  * **Details**
  *
@@ -3251,8 +3472,8 @@ export function isFinite(annotations) {
   });
 }
 /**
- * Generic factory for creating a "greater than" (`>`) check for any ordered
- * type by supplying an {@link Order.Order} instance.
+ * Creates a greater-than (`>`) check for any ordered type from an
+ * `Order.Order` instance.
  *
  * @category Order checks
  * @since 4.0.0
@@ -3269,8 +3490,8 @@ export function makeIsGreaterThan(options) {
   };
 }
 /**
- * Generic factory for creating a ">=" check for any ordered type by supplying
- * an {@link Order.Order} instance.
+ * Creates a greater-than-or-equal-to (`>=`) check for any ordered type from an
+ * `Order.Order` instance.
  *
  * @category Order checks
  * @since 4.0.0
@@ -3287,8 +3508,8 @@ export function makeIsGreaterThanOrEqualTo(options) {
   };
 }
 /**
- * Generic factory for creating a "<" check for any ordered type by supplying
- * an {@link Order.Order} instance.
+ * Creates a less-than (`<`) check for any ordered type from an `Order.Order`
+ * instance.
  *
  * @category Order checks
  * @since 4.0.0
@@ -3305,8 +3526,8 @@ export function makeIsLessThan(options) {
   };
 }
 /**
- * Generic factory for creating a "<=" check for any ordered type by supplying
- * an {@link Order.Order} instance.
+ * Creates a less-than-or-equal-to (`<=`) check for any ordered type from an
+ * `Order.Order` instance.
  *
  * @category Order checks
  * @since 4.0.0
@@ -3323,8 +3544,8 @@ export function makeIsLessThanOrEqualTo(options) {
   };
 }
 /**
- * Generic factory for creating an inclusive/exclusive range check for any
- * ordered type by supplying an {@link Order.Order} instance.
+ * Creates an inclusive or exclusive range check for any ordered type from an
+ * `Order.Order` instance.
  *
  * @category Order checks
  * @since 4.0.0
@@ -3346,8 +3567,8 @@ export function makeIsBetween(deriveOptions) {
   };
 }
 /**
- * Generic factory for creating a divisibility check for any numeric type by
- * supplying a remainder function and a zero value.
+ * Creates a divisibility check for any numeric type from a remainder function
+ * and a zero value.
  *
  * @category Numeric checks
  * @since 4.0.0
@@ -4506,7 +4727,7 @@ export function isUnique(annotations) {
   });
 }
 /**
- * A schema for non-empty strings. Validates that a string has at least one
+ * Schema for non-empty strings. Validates that a string has at least one
  * character.
  *
  * @category String
@@ -4514,7 +4735,7 @@ export function isUnique(annotations) {
  */
 export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty());
 /**
- * A schema for strings whose JavaScript `length` is exactly `1`.
+ * Schema for strings whose JavaScript `length` is exactly `1`.
  *
  * **When to use**
  *
@@ -4534,7 +4755,7 @@ export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty(
  */
 export const Char = /*#__PURE__*/String.check(/*#__PURE__*/isLengthBetween(1, 1));
 /**
- * Creates a schema for `Option<A>`. See {@link Option} for details.
+ * Schema for `Option<A>` values.
  *
  * @category Option
  * @since 3.10.0
@@ -4718,9 +4939,9 @@ export function OptionFromOptionalNullOr(schema, options) {
   })));
 }
 /**
- * Creates a schema for `Result<A, E>`. See {@link Result} for details.
+ * Schema for `Result<A, E>` values.
  *
- * @category Result
+ * @category schemas
  * @since 4.0.0
  */
 export function Result(success, failure) {
@@ -4784,8 +5005,8 @@ export function Result(success, failure) {
   });
 }
 /**
- * Creates a schema for the `Redacted` type, providing secure handling of
- * sensitive information.
+ * Schema for values that hide sensitive information from error output and
+ * inspection.
  *
  * **Details**
  *
@@ -5068,7 +5289,7 @@ const ErrorJsonEncoded = /*#__PURE__*/Struct({
   stack: /*#__PURE__*/optionalKey(String)
 });
 /**
- * A schema for JavaScript `Error` objects.
+ * Schema for JavaScript `Error` objects.
  *
  * **Details**
  *
@@ -5093,7 +5314,7 @@ export const Error = /*#__PURE__*/instanceOf(globalThis.Error, {
   toArbitrary: () => fc => fc.string().map(message => new globalThis.Error(message))
 });
 /**
- * A schema for JavaScript `Error` objects that preserves stack traces in the JSON
+ * Schema for JavaScript `Error` objects that preserves stack traces in the JSON
  * encoded form.
  *
  * **Details**
@@ -5127,7 +5348,7 @@ const defectTransformation = /*#__PURE__*/new Transformation.Transformation(/*#_
   }
 }));
 /**
- * A schema for defect values, accepting either JavaScript `Error` values encoded
+ * Schema for defect values, accepting either JavaScript `Error` values encoded
  * with `message` and optional `name`, or arbitrary unknown defect values.
  *
  * **Details**
@@ -5144,8 +5365,7 @@ export const Defect = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded.pipe(/*#
   toArbitrary: () => fc => fc.json()
 }), defectTransformation))]);
 /**
- * A schema that represents defects, that also includes stack traces in the
- * encoded form.
+ * Schema for defects that also includes stack traces in the encoded form.
  *
  * @category Defect
  * @since 4.0.0
@@ -5244,8 +5464,8 @@ export function Exit(value, error, defect) {
   });
 }
 /**
- * Creates a schema that validates a `ReadonlyMap` where keys and values must
- * conform to the provided schemas.
+ * Schema for readonly maps whose keys and values conform to the provided
+ * schemas.
  *
  * @category ReadonlyMap
  * @since 3.10.0
@@ -5297,8 +5517,7 @@ export function ReadonlyMap(key, value) {
   });
 }
 /**
- * Creates a schema that validates a `HashMap` where keys and values must
- * conform to the provided schemas.
+ * Schema for hash maps whose keys and values conform to the provided schemas.
  *
  * @category HashMap
  * @since 3.10.0
@@ -5351,8 +5570,7 @@ export function HashMap(key, value) {
   });
 }
 /**
- * Creates a schema that validates a `ReadonlySet` whose values conform to the
- * provided element schema.
+ * Schema for readonly sets whose values conform to the provided element schema.
  *
  * @category ReadonlySet
  * @since 3.10.0
@@ -5403,8 +5621,7 @@ export function ReadonlySet(value) {
   });
 }
 /**
- * Creates a schema that validates a `HashSet` where values must conform to the
- * provided schema.
+ * Schema for hash sets whose values conform to the provided element schema.
  *
  * @category HashSet
  * @since 3.10.0
@@ -5455,8 +5672,7 @@ export function HashSet(value) {
   });
 }
 /**
- * Creates a schema that validates a `Chunk` where values must conform to the
- * provided schema.
+ * Schema for chunks whose values conform to the provided element schema.
  *
  * @category Chunk
  * @since 3.10.0
@@ -5551,7 +5767,7 @@ const URLString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a URL"
 });
 /**
- * A schema for JavaScript `URL` objects.
+ * Schema for JavaScript `URL` objects.
  *
  * **Details**
  *
@@ -5576,7 +5792,7 @@ export const URL = /*#__PURE__*/instanceOf(globalThis.URL, {
   toEquivalence: () => (a, b) => a.toString() === b.toString()
 });
 /**
- * A transformation schema that decodes a `string` into a `URL`.
+ * Schema that decodes a `string` into a `URL`.
  *
  * **Details**
  *
@@ -5594,7 +5810,7 @@ const DateString = /*#__PURE__*/String.annotate({
   expected: "a string in ISO 8601 format that will be decoded as a Date"
 });
 /**
- * A schema for JavaScript `Date` objects.
+ * Schema for JavaScript `Date` objects.
  *
  * **When to use**
  *
@@ -5634,7 +5850,7 @@ export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
   toArbitrary: () => (fc, ctx) => fc.date(ctx?.constraints?.date)
 });
 /**
- * A transformation schema that decodes a string into a JavaScript `Date`.
+ * Schema that decodes a string into a JavaScript `Date`.
  *
  * **When to use**
  *
@@ -5662,7 +5878,7 @@ export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
  */
 export const DateFromString = /*#__PURE__*/DateString.pipe(/*#__PURE__*/decodeTo(Date, Transformation.dateFromString));
 /**
- * A schema for **valid** JavaScript `Date` objects.
+ * Schema for **valid** JavaScript `Date` objects.
  *
  * **Details**
  *
@@ -5674,7 +5890,7 @@ export const DateFromString = /*#__PURE__*/DateString.pipe(/*#__PURE__*/decodeTo
  */
 export const DateValid = /*#__PURE__*/Date.check(/*#__PURE__*/isDateValid());
 /**
- * A schema for `Duration` values.
+ * Schema for `Duration` values.
  *
  * **Details**
  *
@@ -5758,7 +5974,7 @@ const DurationString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a Duration"
 });
 /**
- * A transformation schema that parses a string into a `Duration`.
+ * Schema that parses a string into a `Duration`.
  *
  * **Details**
  *
@@ -5775,7 +5991,7 @@ const DurationString = /*#__PURE__*/String.annotate({
 export const DurationFromString = /*#__PURE__*/DurationString.pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromString));
 const bigint0 = /*#__PURE__*/globalThis.BigInt(0);
 /**
- * A transformation schema that decodes a non-negative `bigint` into a
+ * Schema that decodes a non-negative `bigint` into a
  * `Duration`, treating the bigint as nanoseconds.
  *
  * **Details**
@@ -5793,7 +6009,7 @@ const bigint0 = /*#__PURE__*/globalThis.BigInt(0);
  */
 export const DurationFromNanos = /*#__PURE__*/BigInt.check(isGreaterThanOrEqualToBigInt(bigint0)).pipe(/*#__PURE__*/decodeTo(Duration, Transformation.durationFromNanos));
 /**
- * A transformation schema that decodes a non-negative (possibly infinite)
+ * Schema that decodes a non-negative (possibly infinite)
  * integer into a `Duration`, treating the integer value as the duration in
  * milliseconds.
  *
@@ -5815,12 +6031,12 @@ const BigDecimalString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a BigDecimal"
 });
 /**
- * A schema for `BigDecimal` values.
+ * Schema for `BigDecimal` values.
  *
  * **When to use**
  *
- * Use when values are already `BigDecimal` instances and need schema validation,
- * formatting, equivalence, and JSON string serialization.
+ * Use when values are already Effect decimal instances and need schema
+ * validation, formatting, equivalence, and JSON string serialization.
  *
  * **Details**
  *
@@ -5852,7 +6068,7 @@ export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
   toEquivalence: () => BigDecimal_.Equivalence
 });
 /**
- * A transformation schema that parses a string into a `BigDecimal`.
+ * Schema that parses a string into a `BigDecimal`.
  *
  * **When to use**
  *
@@ -5880,7 +6096,7 @@ export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
  */
 export const BigDecimalFromString = /*#__PURE__*/BigDecimalString.pipe(/*#__PURE__*/decodeTo(BigDecimal, Transformation.bigDecimalFromString));
 /**
- * A transformation schema that decodes a JSON-encoded string into an `unknown` value.
+ * Schema that decodes a JSON-encoded string into an `unknown` value.
  *
  * **Details**
  *
@@ -6084,9 +6300,11 @@ export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
   }))
 });
 /**
- * `Schema.fromFormData` returns a schema that reads a `FormData` instance,
- * converts it into a tree record using bracket notation, and then decodes the
- * resulting structure using the provided schema.
+ * Schema for decoding `FormData` through a bracket-notation tree.
+ *
+ * **When to use**
+ *
+ * Use to decode browser or multipart form data into a structured schema value.
  *
  * **Details**
  *
@@ -6199,9 +6417,11 @@ export const URLSearchParams = /*#__PURE__*/instanceOf(globalThis.URLSearchParam
   }))
 });
 /**
- * `Schema.fromURLSearchParams` returns a schema that reads a `URLSearchParams`
- * instance, converts it into a tree record using bracket notation, and then
- * decodes the resulting structure using the provided schema.
+ * Schema for decoding `URLSearchParams` through a bracket-notation tree.
+ *
+ * **When to use**
+ *
+ * Use to decode query parameters into a structured schema value.
  *
  * **Details**
  *
@@ -6280,21 +6500,21 @@ export function fromURLSearchParams(schema) {
   return URLSearchParams.pipe(decodeTo(schema, Transformation.fromURLSearchParams));
 }
 /**
- * A schema for finite numbers, rejecting `NaN`, `Infinity`, and `-Infinity`.
+ * Schema for finite numbers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
  * @category Number
  * @since 3.10.0
  */
 export const Finite = /*#__PURE__*/Number.check(/*#__PURE__*/isFinite());
 /**
- * A schema for integers, rejecting `NaN`, `Infinity`, and `-Infinity`.
+ * Schema for integers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
  * @category Number
  * @since 3.10.0
  */
 export const Int = /*#__PURE__*/Number.check(/*#__PURE__*/isInt());
 /**
- * A transformation schema that parses a string into a `number` using JavaScript
+ * Schema that parses a string into a `number` using JavaScript
  * number coercion.
  *
  * **Details**
@@ -6314,7 +6534,7 @@ export const NumberFromString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a number"
 }).pipe(/*#__PURE__*/decodeTo(Number, Transformation.numberFromString));
 /**
- * A transformation schema that parses a string into a finite number.
+ * Schema that parses a string into a finite number.
  *
  * **Details**
  *
@@ -6332,7 +6552,7 @@ export const FiniteFromString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a finite number"
 }).pipe(/*#__PURE__*/decodeTo(Finite, Transformation.numberFromString));
 /**
- * A transformation schema that parses a string into a `bigint`.
+ * Schema that parses a string into a `bigint`.
  *
  * **When to use**
  *
@@ -6361,14 +6581,14 @@ export const FiniteFromString = /*#__PURE__*/String.annotate({
  */
 export const BigIntFromString = /*#__PURE__*/make(AST.bigIntString).pipe(/*#__PURE__*/decodeTo(BigInt, Transformation.bigintFromString));
 /**
- * A schema for strings that contains no leading or trailing whitespaces.
+ * Schema for strings that contains no leading or trailing whitespaces.
  *
  * @category String
  * @since 3.10.0
  */
 export const Trimmed = /*#__PURE__*/String.check(/*#__PURE__*/isTrimmed());
 /**
- * A transformation schema that trims whitespace from a string.
+ * Schema that trims whitespace from a string.
  *
  * **Details**
  *
@@ -6472,7 +6692,7 @@ export const StringFromUriComponent = /*#__PURE__*/String.annotate({
   expected: "a URI component encoded string that will be decoded as a UTF-8 string"
 }).pipe(/*#__PURE__*/decodeTo(String, Transformation.stringFromUriComponent));
 /**
- * A union schema for property keys accepted by Effect schemas: finite `number`,
+ * Schema for property keys accepted by Effect schemas: finite `number`,
  * `symbol`, or `string`.
  *
  * @category PropertyKey
@@ -6499,7 +6719,7 @@ export const StandardSchemaV1FailureResult = /*#__PURE__*/Struct({
   }))
 });
 /**
- * A boolean parsed from 0 or 1.
+ * Schema for a boolean parsed from 0 or 1.
  *
  * **When to use**
  *
@@ -6527,7 +6747,7 @@ const Base64String = /*#__PURE__*/String.annotate({
   contentEncoding: "base64"
 });
 /**
- * A schema for JavaScript `Uint8Array` objects.
+ * Schema for JavaScript `Uint8Array` objects.
  *
  * **Details**
  *
@@ -6551,7 +6771,7 @@ export const Uint8Array = /*#__PURE__*/instanceOf(globalThis.Uint8Array, {
   toArbitrary: () => fc => fc.uint8Array()
 });
 /**
- * A transformation schema that decodes a base64 encoded string into a
+ * Schema that decodes a base64 encoded string into a
  * `Uint8Array`.
  *
  * **Details**
@@ -6567,7 +6787,7 @@ export const Uint8Array = /*#__PURE__*/instanceOf(globalThis.Uint8Array, {
  */
 export const Uint8ArrayFromBase64 = /*#__PURE__*/Base64String.pipe(/*#__PURE__*/decodeTo(Uint8Array, Transformation.uint8ArrayFromBase64String));
 /**
- * A transformation schema that decodes a base64 (URL) encoded string into a
+ * Schema that decodes a base64 (URL) encoded string into a
  * `Uint8Array`.
  *
  * **Details**
@@ -6588,7 +6808,7 @@ export const Uint8ArrayFromBase64Url = /*#__PURE__*/String.annotate({
   encode: /*#__PURE__*/Getter.encodeBase64Url()
 }));
 /**
- * A transformation schema that decodes a hex encoded string into a
+ * Schema that decodes a hex encoded string into a
  * `Uint8Array`.
  *
  * **Details**
@@ -6609,7 +6829,7 @@ export const Uint8ArrayFromHex = /*#__PURE__*/String.annotate({
   encode: /*#__PURE__*/Getter.encodeHex()
 }));
 /**
- * A schema for `DateTime.Utc` values.
+ * Schema for `DateTime.Utc` values.
  *
  * **When to use**
  *
@@ -6648,7 +6868,7 @@ export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && D
   toEquivalence: () => DateTime.Equivalence
 });
 /**
- * A transformation schema that decodes a `Date` into a `DateTime.Utc`.
+ * Schema that decodes a `Date` into a `DateTime.Utc`.
  *
  * **When to use**
  *
@@ -6676,7 +6896,7 @@ export const DateTimeUtcFromDate = /*#__PURE__*/DateValid.pipe(/*#__PURE__*/deco
   encode: /*#__PURE__*/Getter.transform(DateTime.toDateUtc)
 }));
 /**
- * A transformation schema that decodes a date-time string into a `DateTime.Utc`.
+ * Schema that decodes a date-time string into a `DateTime.Utc`.
  *
  * **Details**
  *
@@ -6696,7 +6916,7 @@ export const DateTimeUtcFromString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a DateTime.Utc"
 }).pipe(/*#__PURE__*/decodeTo(DateTimeUtc, Transformation.dateTimeUtcFromString));
 /**
- * A transformation schema that decodes a number into a `DateTime.Utc`.
+ * Schema that decodes a number into a `DateTime.Utc`.
  *
  * **Details**
  *
@@ -6714,7 +6934,7 @@ export const DateTimeUtcFromMillis = /*#__PURE__*/Number.pipe(/*#__PURE__*/decod
   encode: /*#__PURE__*/Getter.transform(DateTime.toEpochMillis)
 }));
 /**
- * A schema for `DateTime.TimeZone.Offset` values.
+ * Schema for `DateTime.TimeZone.Offset` values.
  *
  * **Details**
  *
@@ -6747,7 +6967,7 @@ const TimeZoneNamedString = /*#__PURE__*/String.annotate({
   expected: "an IANA time zone identifier"
 });
 /**
- * A schema for `DateTime.TimeZone.Named` values.
+ * Schema for `DateTime.TimeZone.Named` values.
  *
  * **Details**
  *
@@ -6774,7 +6994,7 @@ export const TimeZoneNamed = /*#__PURE__*/declare(DateTime.isTimeZoneNamed, {
   toEquivalence: () => (a, b) => a.id === b.id
 });
 /**
- * A transformation schema that parses an IANA time zone identifier string into a `DateTime.TimeZone.Named`.
+ * Schema that parses an IANA time zone identifier string into a `DateTime.TimeZone.Named`.
  *
  * **Details**
  *
@@ -6792,7 +7012,7 @@ const TimeZoneString = /*#__PURE__*/String.annotate({
   expected: "a time zone string (IANA identifier or offset like +03:00)"
 });
 /**
- * A schema for `DateTime.TimeZone` values.
+ * Schema for `DateTime.TimeZone` values.
  *
  * **Details**
  *
@@ -6823,7 +7043,7 @@ export const TimeZone = /*#__PURE__*/declare(DateTime.isTimeZone, {
   toEquivalence: () => (a, b) => DateTime.zoneToString(a) === DateTime.zoneToString(b)
 });
 /**
- * A transformation schema that parses a time zone string into a `DateTime.TimeZone`.
+ * Schema that parses a time zone string into a `DateTime.TimeZone`.
  *
  * **Details**
  *
@@ -6841,7 +7061,7 @@ const DateTimeZonedString = /*#__PURE__*/String.annotate({
   expected: "a zoned DateTime string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London])"
 });
 /**
- * A schema for `DateTime.Zoned` values.
+ * Schema for `DateTime.Zoned` values.
  *
  * **Details**
  *
@@ -6878,7 +7098,7 @@ export const DateTimeZoned = /*#__PURE__*/declare(u => DateTime.isDateTime(u) &&
   toEquivalence: () => DateTime.Equivalence
 });
 /**
- * A transformation schema that parses a zoned DateTime string into a `DateTime.Zoned`.
+ * Schema that parses a zoned DateTime string into a `DateTime.Zoned`.
  *
  * **Details**
  *
@@ -7063,9 +7283,12 @@ export const Class = identifier => (schema, annotations) => {
   }));
 };
 /**
- * Like {@link Class} but automatically adds a `_tag` literal field set to the
- * given `tag` value. This makes instances compatible with tagged union
- * discrimination patterns.
+ * Defines a schema-backed class with an automatically populated `_tag` field.
+ *
+ * **When to use**
+ *
+ * Use to define class instances that are validated by a schema and participate
+ * in tagged union matching.
  *
  * **Details**
  *
@@ -7131,9 +7354,13 @@ export const ErrorClass = identifier => (schema, annotations) => {
   return self;
 };
 /**
- * Like {@link ErrorClass} but automatically adds a `_tag` literal field. The
- * resulting class is both a schema-validated, yieldable error and a tagged
- * union member.
+ * Defines a schema-backed yieldable error class with an automatically populated
+ * `_tag` field.
+ *
+ * **When to use**
+ *
+ * Use to define typed errors that are schema validated, yielded in `Effect.gen`,
+ * and matched as tagged union members.
  *
  * **Example** (Tagged error class)
  *
@@ -7207,7 +7434,7 @@ export function toArbitrary(schema) {
 // Formatter
 // -----------------------------------------------------------------------------
 /**
- * Annotates a schema with a custom formatter used by `toFormatter`.
+ * Attaches a custom formatter used by `toFormatter`.
  *
  * **Details**
  *
@@ -7374,8 +7601,12 @@ export function toFormatter(schema, options) {
 // -----------------------------------------------------------------------------
 /**
  * Overrides the equivalence derivation for a schema by supplying a custom
- * `Equivalence`. Use this when the default structural equivalence derived by
- * {@link toEquivalence} is not appropriate for a type.
+ * `Equivalence`.
+ *
+ * **When to use**
+ *
+ * Use when the default structural equivalence derived by {@link toEquivalence}
+ * is not appropriate for a type.
  *
  * @category Equivalence
  * @since 4.0.0
@@ -7795,12 +8026,19 @@ export function toIsoFocus(_) {
   return Optic_.id();
 }
 /**
- * Overrides the ISO codec derivation for a schema by providing a target codec
- * and explicit `decode`/`encode` getters. The resulting schema carries a
- * custom `Iso` type, which changes the schema's type parameter — use
- * {@link overrideToCodecIso} when the default ISO transformation is not
+ * Overrides a schema's derived ISO codec with an explicit target codec.
+ *
+ * **When to use**
+ *
+ * Use to provide a custom ISO transformation when the default derivation is not
  * appropriate.
  *
+ * **Details**
+ *
+ * The resulting schema carries a custom `Iso` type parameter and uses the
+ * provided `decode` and `encode` getters to transform between the schema type
+ * and the target codec.
+ *
  * @category Optic
  * @since 4.0.0
  */