effect 4.0.0-beta.71 → 4.0.0-beta.73

package/dist/Schema.d.ts

@@ -369,7 +369,7 @@ export interface declare<T, Iso = T> extends declareConstructor<T, T, readonly [
  */
 export declare function declare<T, Iso = T>(is: (u: unknown) => u is T, annotations?: Annotations.Declaration<T> | undefined): declare<T, Iso>;
 /**
- * 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**
@@ -742,8 +742,8 @@ export interface Encoder<out E, out RE = never> extends Codec<unknown, E, unknow
     readonly "Rebuild": Encoder<E, RE>;
 }
 /**
- * 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**
  *
@@ -890,7 +890,7 @@ export declare function toStandardSchemaV1<S extends Decoder<unknown>>(self: S,
     readonly parseOptions?: AST.ParseOptions | undefined;
 }): StandardSchemaV1<S["Encoded"], S["Type"]> & S;
 /**
- * Experimental support for converting a schema to a Standard JSON Schema V1.
+ * Converts a schema to an experimental Standard JSON Schema V1 representation.
  *
  * **Details**
  *
@@ -936,11 +936,15 @@ export declare const is: typeof 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)
  *
@@ -968,9 +972,16 @@ export declare const is: typeof Parser.is;
 export declare const asserts: <S extends Top, I>(schema: S, input: I) => asserts input is I & S["Type"];
 /**
  * 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.
  *
@@ -981,8 +992,15 @@ export declare function decodeUnknownEffect<S extends Top>(schema: S, 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.
  *
@@ -993,9 +1011,18 @@ export declare const decodeEffect: <S extends Top>(schema: S, options?: AST.Pars
 /**
  * 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.
  *
@@ -1006,9 +1033,17 @@ export declare function decodeUnknownExit<S extends Decoder<unknown>>(schema: S,
 /**
  * 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.
  *
@@ -1018,10 +1053,17 @@ export declare function decodeUnknownExit<S extends Decoder<unknown>>(schema: S,
 export declare const decodeExit: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Exit_.Exit<S["Type"], SchemaError>;
 /**
  * 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.
  *
@@ -1032,7 +1074,15 @@ export declare const decodeUnknownOption: typeof 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.
  *
@@ -1042,8 +1092,16 @@ export declare const decodeUnknownOption: typeof Parser.decodeUnknownOption;
 export declare const decodeOption: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Option_.Option<S["Type"]>;
 /**
  * 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.
  *
@@ -1054,7 +1112,16 @@ export declare const decodeUnknownResult: typeof 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.
  *
@@ -1064,9 +1131,15 @@ export declare const decodeUnknownResult: typeof Parser.decodeUnknownResult;
 export declare const decodeResult: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => Result_.Result<S["Type"], Issue.Issue>;
 /**
  * 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.
  *
@@ -1077,10 +1150,15 @@ export declare const decodeUnknownPromise: typeof 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.
  *
@@ -1091,11 +1169,15 @@ export declare const decodePromise: typeof 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
@@ -1125,10 +1207,16 @@ export declare const decodeUnknownSync: typeof 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.
@@ -1139,9 +1227,16 @@ export declare const decodeUnknownSync: typeof Parser.decodeUnknownSync;
 export declare const decodeSync: <S extends Decoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Encoded"], options?: AST.ParseOptions) => S["Type"];
 /**
  * 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.
  *
@@ -1163,8 +1258,15 @@ export declare function encodeUnknownEffect<S extends Top>(schema: S, 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.
  *
@@ -1175,9 +1277,17 @@ export declare const encodeEffect: <S extends Top>(schema: S, options?: AST.Pars
 /**
  * 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.
  *
@@ -1188,9 +1298,17 @@ export declare function encodeUnknownExit<S extends Encoder<unknown>>(schema: S,
 /**
  * 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.
  *
@@ -1200,10 +1318,17 @@ export declare function encodeUnknownExit<S extends Encoder<unknown>>(schema: S,
 export declare const encodeExit: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Exit_.Exit<S["Encoded"], SchemaError>;
 /**
  * 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.
  *
@@ -1214,7 +1339,15 @@ export declare const encodeUnknownOption: typeof 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.
  *
@@ -1224,8 +1357,16 @@ export declare const encodeUnknownOption: typeof Parser.encodeUnknownOption;
 export declare const encodeOption: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Option_.Option<S["Encoded"]>;
 /**
  * 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.
  *
@@ -1236,6 +1377,14 @@ export declare const encodeUnknownResult: typeof 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.
@@ -1246,9 +1395,15 @@ export declare const encodeUnknownResult: typeof Parser.encodeUnknownResult;
 export declare const encodeResult: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Result_.Result<S["Encoded"], Issue.Issue>;
 /**
  * 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.
  *
@@ -1259,7 +1414,15 @@ export declare const encodeUnknownPromise: <S extends Encoder<unknown>>(schema:
 /**
  * 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.
  *
@@ -1269,9 +1432,16 @@ export declare const encodeUnknownPromise: <S extends Encoder<unknown>>(schema:
 export declare const encodePromise: <S extends Encoder<unknown>>(schema: S, options?: AST.ParseOptions) => (input: S["Type"], options?: AST.ParseOptions) => Promise<S["Encoded"]>;
 /**
  * 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;
@@ -1283,8 +1453,16 @@ export declare const encodePromise: <S extends Encoder<unknown>>(schema: S, opti
 export declare const encodeUnknownSync: typeof 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.
  *
@@ -1335,7 +1513,7 @@ export declare function asClass<S extends Top>(schema: S): S & {
     new (_: never): {};
 };
 /**
- * Tests if a value is a `Schema`.
+ * Checks whether a value is a `Schema`.
  *
  * @category guards
  * @since 3.10.0
@@ -1384,8 +1562,12 @@ interface requiredKeyLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends optionalKey<Top> ? this["~lambda.in"]["schema"] : "Error: schema not eligible for requiredKey";
 }
 /**
- * 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
@@ -1440,8 +1622,16 @@ interface requiredLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends optional<Top> ? this["~lambda.in"]["schema"]["members"][0] : "Error: schema not eligible for required";
 }
 /**
- * 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
@@ -1474,8 +1664,12 @@ interface readonlyKeyLambda extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends mutableKey<Top> ? this["~lambda.in"]["schema"] : "Error: schema not eligible for readonlyKey";
 }
 /**
- * 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
@@ -1536,8 +1730,15 @@ export interface flip<S extends Top> extends Bottom<S["Encoded"], S["Type"], S["
     readonly schema: S;
 }
 /**
- * Swaps the `Type` and `Encoded` of a schema, inverting the transformation
- * direction. Calling `flip` twice returns the original schema.
+ * Swaps the decoded and encoded sides of a schema.
+ *
+ * **When to use**
+ *
+ * Use to invert a schema transformation direction.
+ *
+ * **Details**
+ *
+ * Calling `flip` twice returns the original schema.
  *
  * **Example** (Flip a number-from-string schema)
  *
@@ -1698,8 +1899,17 @@ export interface TemplateLiteralParser<Parts extends TemplateLiteral.Parts> exte
     readonly parts: 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)
  *
@@ -2245,8 +2455,16 @@ interface fieldsAssign<NewFields extends Struct.Fields> extends Lambda {
     readonly "~lambda.out": this["~lambda.in"] extends Struct<Struct.Fields> ? Struct<Struct_.Simplify<Struct_.Assign<this["~lambda.in"]["fields"], NewFields>>> : "Error: schema not eligible for fieldsAssign";
 }
 /**
- * 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)
  *
@@ -2640,8 +2858,8 @@ export declare namespace StructWithRest {
  *
  * **When to use**
  *
- * Use as the schema type returned by `StructWithRest` when generic code needs to
- * retain the base struct schema and all rest record schemas.
+ * Use as the schema type when generic code needs to retain the base struct
+ * schema and all rest record schemas.
  *
  * @see {@link StructWithRest} for constructing this schema type
  * @see {@link Record} for constructing record schemas used as rest index signatures
@@ -3077,8 +3295,8 @@ export declare const NonEmptyArray: NonEmptyArrayLambda;
  *
  * **When to use**
  *
- * Use as the schema type returned by `ArrayEnsure` when generic code needs to
- * retain the original item schema.
+ * Use as the schema type when generic code needs to retain the original item
+ * schema.
  *
  * **Details**
  *
@@ -3382,8 +3600,8 @@ export interface suspend<S extends Top> extends Bottom<S["Type"], S["Encoded"],
  */
 export declare function suspend<S extends Top>(f: () => S): suspend<S>;
 /**
- * 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)
  *
@@ -3432,8 +3650,8 @@ type DistributeBrands<B> = UnionToIntersection<B extends infer U extends string
  *
  * **When to use**
  *
- * Use as the schema type returned by `brand` when generic code needs to retain
- * the wrapped schema and nominal brand type.
+ * Use as the schema type when generic code needs to retain the wrapped schema
+ * and nominal brand type.
  *
  * @see {@link brand} for adding the brand tag to an existing schema
  *
@@ -3580,7 +3798,7 @@ export declare function middlewareEncoding<S extends Top, RE>(encode: (effect: E
  */
 export declare function catchDecoding<S extends Top>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Type"]>, Issue.Issue>): (self: S) => S["Rebuild"];
 /**
- * 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**
  *
@@ -3613,7 +3831,7 @@ export declare function catchDecodingWithContext<S extends Top, R = never>(f: (i
  */
 export declare function catchEncoding<S extends Top>(f: (issue: Issue.Issue) => Effect.Effect<Option_.Option<S["Encoded"]>, Issue.Issue>): (self: S) => S["Rebuild"];
 /**
- * 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**
  *
@@ -3759,13 +3977,17 @@ export declare function decode<S extends Top, RD = never, RE = never>(transforma
     readonly encode: Getter.Getter<S["Type"], S["Type"], RE>;
 }): (self: S) => decodeTo<toType<S>, S, RD, RE>;
 /**
- * Like {@link decodeTo} but reverses the direction: the `from` schema acts as the target (decoded type)
- * and `to` acts as the encoded source.
+ * Reverses a schema transformation so the encoded schema is supplied first.
+ *
+ * **When to use**
+ *
+ * Use to define a transformation by naming the encoded schema before the
+ * decoded schema.
  *
  * **Details**
  *
- * `encodeTo(to)(from)` is equivalent to `to.pipe(decodeTo(from))` — useful when it reads more
- * naturally to specify the encoded schema first.
+ * `encodeTo(to)(from)` is equivalent to `to.pipe(decodeTo(from))`. The `from`
+ * schema acts as the target decoded schema and `to` acts as the encoded source.
  *
  * **Example** (Encode a number back to string)
  *
@@ -4090,9 +4312,17 @@ export interface tag<Tag extends AST.LiteralValue> extends withConstructorDefaul
  */
 export declare function tag<Tag extends AST.LiteralValue>(literal: Tag): tag<Tag>;
 /**
- * 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)
  *
@@ -4125,9 +4355,11 @@ export type TaggedStruct<Tag extends AST.LiteralValue, Fields extends Struct.Fie
     readonly _tag: tag<Tag>;
 } & Fields>>;
 /**
- * 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**
  *
@@ -4774,8 +5006,8 @@ export declare function isUncapitalized(annotations?: Annotations.Filter): AST.F
  */
 export declare function isFinite(annotations?: Annotations.Filter): AST.Filter<number>;
 /**
- * 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
@@ -4786,8 +5018,8 @@ export declare function makeIsGreaterThan<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (exclusiveMinimum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
- * 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
@@ -4798,8 +5030,8 @@ export declare function makeIsGreaterThanOrEqualTo<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (minimum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
- * 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
@@ -4810,8 +5042,8 @@ export declare function makeIsLessThan<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (exclusiveMaximum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
- * 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
@@ -4822,8 +5054,8 @@ export declare function makeIsLessThanOrEqualTo<T>(options: {
     readonly formatter?: Formatter<T> | undefined;
 }): (maximum: T, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
- * 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
@@ -4844,8 +5076,8 @@ export declare function makeIsBetween<T>(deriveOptions: {
     readonly exclusiveMaximum?: boolean | undefined;
 }, annotations?: Annotations.Filter) => AST.Filter<T>;
 /**
- * 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
@@ -5560,7 +5792,7 @@ export interface NonEmptyString extends String {
     readonly "Rebuild": NonEmptyString;
 }
 /**
- * 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
@@ -5578,7 +5810,7 @@ export interface Char extends String {
     readonly "Rebuild": Char;
 }
 /**
- * A schema for strings whose JavaScript `length` is exactly `1`.
+ * Schema for strings whose JavaScript `length` is exactly `1`.
  *
  * **When to use**
  *
@@ -5639,7 +5871,7 @@ export type OptionIso<A extends Top> = {
     readonly value: A["Iso"];
 };
 /**
- * Creates a schema for `Option<A>`. See {@link Option} for details.
+ * Schema for `Option<A>` values.
  *
  * @category Option
  * @since 3.10.0
@@ -5822,7 +6054,7 @@ export declare function OptionFromOptionalNullOr<S extends Top>(schema: S, optio
  * Schema for the `Result<A, E>` type, representing a computation that either
  * succeeds with `A` or fails with `E`.
  *
- * @category Result
+ * @category schemas
  * @since 4.0.0
  */
 export interface Result<A extends Top, E extends Top> extends declareConstructor<Result_.Result<A["Type"], E["Type"]>, Result_.Result<A["Encoded"], E["Encoded"]>, readonly [A, E], ResultIso<A, E>> {
@@ -5838,7 +6070,7 @@ export interface Result<A extends Top, E extends Top> extends declareConstructor
  * Successful results are represented as `{ _tag: "Success", success }`, while
  * failed results are represented as `{ _tag: "Failure", failure }`.
  *
- * @category Result
+ * @category schemas
  * @since 4.0.0
  */
 export type ResultIso<A extends Top, E extends Top> = {
@@ -5849,9 +6081,9 @@ export type ResultIso<A extends Top, E extends Top> = {
     readonly failure: E["Iso"];
 };
 /**
- * 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 declare function Result<A extends Top, E extends Top>(success: A, failure: E): Result<A, E>;
@@ -5867,8 +6099,8 @@ export interface Redacted<S extends Top> extends declareConstructor<Redacted_.Re
     readonly value: S;
 }
 /**
- * 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**
  *
@@ -5930,8 +6162,8 @@ export declare function RedactedFromValue<S extends Top>(value: S, options?: {
  *
  * **When to use**
  *
- * Use as the schema type returned by `CauseReason` when generic code needs to
- * retain the typed failure and defect schemas.
+ * Use as the schema type when generic code needs to retain the typed failure
+ * and defect schemas for a single cause reason.
  *
  * **Details**
  *
@@ -5997,8 +6229,8 @@ export declare function CauseReason<E extends Top, D extends Top>(error: E, defe
  *
  * **When to use**
  *
- * Use as the schema type returned by `Cause` when generic code needs to retain
- * the typed failure and defect schemas.
+ * Use as the schema type when generic code needs to retain the typed failure
+ * and defect schemas for a full cause.
  *
  * **Details**
  *
@@ -6064,7 +6296,7 @@ export interface Error extends instanceOf<globalThis.Error> {
     readonly "Rebuild": Error;
 }
 /**
- * A schema for JavaScript `Error` objects.
+ * Schema for JavaScript `Error` objects.
  *
  * **Details**
  *
@@ -6078,7 +6310,7 @@ export interface Error extends instanceOf<globalThis.Error> {
  */
 export declare const Error: Error;
 /**
- * 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**
@@ -6109,7 +6341,7 @@ export interface Defect extends Union<readonly [
     readonly "Rebuild": Defect;
 }
 /**
- * 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**
@@ -6123,8 +6355,7 @@ export interface Defect extends Union<readonly [
  */
 export declare const Defect: Defect;
 /**
- * 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
@@ -6199,8 +6430,8 @@ export interface $ReadonlyMap<Key extends Top, Value extends Top> extends declar
  */
 export type ReadonlyMapIso<Key extends Top, Value extends Top> = ReadonlyArray<readonly [Key["Iso"], Value["Iso"]]>;
 /**
- * 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
@@ -6227,8 +6458,7 @@ export interface HashMap<Key extends Top, Value extends Top> extends declareCons
  */
 export type HashMapIso<Key extends Top, Value extends Top> = ReadonlyArray<readonly [Key["Iso"], Value["Iso"]]>;
 /**
- * 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
@@ -6262,8 +6492,7 @@ export interface $ReadonlySet<Value extends Top> extends declareConstructor<glob
  */
 export type ReadonlySetIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
 /**
- * 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
@@ -6289,8 +6518,7 @@ export interface HashSet<Value extends Top> extends declareConstructor<HashSet_.
  */
 export type HashSetIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
 /**
- * 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
@@ -6323,8 +6551,7 @@ export interface Chunk<Value extends Top> extends declareConstructor<Chunk_.Chun
  */
 export type ChunkIso<Value extends Top> = ReadonlyArray<Value["Iso"]>;
 /**
- * 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
@@ -6360,7 +6587,7 @@ export interface URL extends instanceOf<globalThis.URL> {
     readonly "Rebuild": URL;
 }
 /**
- * A schema for JavaScript `URL` objects.
+ * Schema for JavaScript `URL` objects.
  *
  * **Details**
  *
@@ -6383,7 +6610,7 @@ export interface URLFromString extends decodeTo<URL, String> {
     readonly "Rebuild": URLFromString;
 }
 /**
- * A transformation schema that decodes a `string` into a `URL`.
+ * Schema that decodes a `string` into a `URL`.
  *
  * **Details**
  *
@@ -6408,7 +6635,7 @@ export interface Date extends instanceOf<globalThis.Date> {
     readonly "Rebuild": Date;
 }
 /**
- * A schema for JavaScript `Date` objects.
+ * Schema for JavaScript `Date` objects.
  *
  * **When to use**
  *
@@ -6447,7 +6674,7 @@ export interface DateFromString extends decodeTo<Date, String> {
     readonly "Rebuild": DateFromString;
 }
 /**
- * A transformation schema that decodes a string into a JavaScript `Date`.
+ * Schema that decodes a string into a JavaScript `Date`.
  *
  * **When to use**
  *
@@ -6485,7 +6712,7 @@ export interface DateValid extends Date {
     readonly "Rebuild": DateValid;
 }
 /**
- * A schema for **valid** JavaScript `Date` objects.
+ * Schema for **valid** JavaScript `Date` objects.
  *
  * **Details**
  *
@@ -6506,7 +6733,7 @@ export interface Duration extends declare<Duration_.Duration> {
     readonly "Rebuild": Duration;
 }
 /**
- * A schema for `Duration` values.
+ * Schema for `Duration` values.
  *
  * **Details**
  *
@@ -6538,7 +6765,7 @@ export interface DurationFromString extends decodeTo<Duration, String> {
     readonly "Rebuild": DurationFromString;
 }
 /**
- * A transformation schema that parses a string into a `Duration`.
+ * Schema that parses a string into a `Duration`.
  *
  * **Details**
  *
@@ -6564,7 +6791,7 @@ export interface DurationFromNanos extends decodeTo<Duration, BigInt> {
     readonly "Rebuild": DurationFromNanos;
 }
 /**
- * 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**
@@ -6592,7 +6819,7 @@ export interface DurationFromMillis extends decodeTo<Duration, Number> {
     readonly "Rebuild": DurationFromMillis;
 }
 /**
- * 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.
  *
@@ -6620,12 +6847,12 @@ export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
     readonly "Rebuild": 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**
  *
@@ -6650,7 +6877,7 @@ export interface BigDecimalFromString extends decodeTo<BigDecimal, String> {
     readonly "Rebuild": BigDecimalFromString;
 }
 /**
- * A transformation schema that parses a string into a `BigDecimal`.
+ * Schema that parses a string into a `BigDecimal`.
  *
  * **When to use**
  *
@@ -6688,7 +6915,7 @@ export interface UnknownFromJsonString extends fromJsonString<Unknown> {
     readonly "Rebuild": UnknownFromJsonString;
 }
 /**
- * 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**
  *
@@ -6843,9 +7070,11 @@ export interface fromFormData<S extends Top> extends decodeTo<S, FormData> {
     readonly "Rebuild": fromFormData<S>;
 }
 /**
- * `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**
  *
@@ -6961,9 +7190,11 @@ export interface fromURLSearchParams<S extends Top> extends decodeTo<S, URLSearc
     readonly "Rebuild": fromURLSearchParams<S>;
 }
 /**
- * `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**
  *
@@ -7050,7 +7281,7 @@ export interface Finite extends Number {
     readonly "Rebuild": Finite;
 }
 /**
- * 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
@@ -7067,7 +7298,7 @@ export interface Int extends Number {
     readonly "Rebuild": Int;
 }
 /**
- * A schema for integers, rejecting `NaN`, `Infinity`, and `-Infinity`.
+ * Schema for integers, rejecting `NaN`, `Infinity`, and `-Infinity`.
  *
  * @category Number
  * @since 3.10.0
@@ -7084,7 +7315,7 @@ export interface NumberFromString extends decodeTo<Finite, String> {
     readonly "Rebuild": NumberFromString;
 }
 /**
- * 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**
@@ -7112,7 +7343,7 @@ export interface FiniteFromString extends decodeTo<Finite, String> {
     readonly "Rebuild": FiniteFromString;
 }
 /**
- * A transformation schema that parses a string into a finite number.
+ * Schema that parses a string into a finite number.
  *
  * **Details**
  *
@@ -7138,7 +7369,7 @@ export interface BigIntFromString extends decodeTo<BigInt, String> {
     readonly "Rebuild": BigIntFromString;
 }
 /**
- * A transformation schema that parses a string into a `bigint`.
+ * Schema that parses a string into a `bigint`.
  *
  * **When to use**
  *
@@ -7177,7 +7408,7 @@ export interface Trimmed extends String {
     readonly "Rebuild": Trimmed;
 }
 /**
- * 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
@@ -7194,7 +7425,7 @@ export interface Trim extends decodeTo<Trimmed, String> {
     readonly "Rebuild": Trim;
 }
 /**
- * A transformation schema that trims whitespace from a string.
+ * Schema that trims whitespace from a string.
  *
  * **Details**
  *
@@ -7328,7 +7559,7 @@ export interface StringFromUriComponent extends decodeTo<String, String> {
  */
 export declare const StringFromUriComponent: 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
@@ -7365,7 +7596,7 @@ export interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0,
     readonly "Rebuild": BooleanFromBit;
 }
 /**
- * A boolean parsed from 0 or 1.
+ * Schema for a boolean parsed from 0 or 1.
  *
  * **When to use**
  *
@@ -7395,7 +7626,7 @@ export interface Uint8Array extends instanceOf<globalThis.Uint8Array<ArrayBuffer
     readonly "Rebuild": Uint8Array;
 }
 /**
- * A schema for JavaScript `Uint8Array` objects.
+ * Schema for JavaScript `Uint8Array` objects.
  *
  * **Details**
  *
@@ -7418,7 +7649,7 @@ export interface Uint8ArrayFromBase64 extends decodeTo<Uint8Array, String> {
     readonly "Rebuild": Uint8ArrayFromBase64;
 }
 /**
- * A transformation schema that decodes a base64 encoded string into a
+ * Schema that decodes a base64 encoded string into a
  * `Uint8Array`.
  *
  * **Details**
@@ -7444,7 +7675,7 @@ export interface Uint8ArrayFromBase64Url extends decodeTo<Uint8Array, String> {
     readonly "Rebuild": Uint8ArrayFromBase64Url;
 }
 /**
- * A transformation schema that decodes a base64 (URL) encoded string into a
+ * Schema that decodes a base64 (URL) encoded string into a
  * `Uint8Array`.
  *
  * **Details**
@@ -7470,7 +7701,7 @@ export interface Uint8ArrayFromHex extends decodeTo<Uint8Array, String> {
     readonly "Rebuild": Uint8ArrayFromHex;
 }
 /**
- * A transformation schema that decodes a hex encoded string into a
+ * Schema that decodes a hex encoded string into a
  * `Uint8Array`.
  *
  * **Details**
@@ -7496,7 +7727,7 @@ export interface DateTimeUtc extends declare<DateTime.Utc> {
     readonly "Rebuild": DateTimeUtc;
 }
 /**
- * A schema for `DateTime.Utc` values.
+ * Schema for `DateTime.Utc` values.
  *
  * **When to use**
  *
@@ -7528,7 +7759,7 @@ export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
     readonly "Rebuild": DateTimeUtcFromDate;
 }
 /**
- * A transformation schema that decodes a `Date` into a `DateTime.Utc`.
+ * Schema that decodes a `Date` into a `DateTime.Utc`.
  *
  * **When to use**
  *
@@ -7563,7 +7794,7 @@ export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
     readonly "Rebuild": DateTimeUtcFromString;
 }
 /**
- * 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**
  *
@@ -7591,7 +7822,7 @@ export interface DateTimeUtcFromMillis extends decodeTo<instanceOf<DateTime.Utc>
     readonly "Rebuild": DateTimeUtcFromMillis;
 }
 /**
- * A transformation schema that decodes a number into a `DateTime.Utc`.
+ * Schema that decodes a number into a `DateTime.Utc`.
  *
  * **Details**
  *
@@ -7616,7 +7847,7 @@ export interface TimeZoneOffset extends declare<DateTime.TimeZone.Offset> {
     readonly "Rebuild": TimeZoneOffset;
 }
 /**
- * A schema for `DateTime.TimeZone.Offset` values.
+ * Schema for `DateTime.TimeZone.Offset` values.
  *
  * **Details**
  *
@@ -7639,7 +7870,7 @@ export interface TimeZoneNamed extends declare<DateTime.TimeZone.Named> {
     readonly "Rebuild": TimeZoneNamed;
 }
 /**
- * A schema for `DateTime.TimeZone.Named` values.
+ * Schema for `DateTime.TimeZone.Named` values.
  *
  * **Details**
  *
@@ -7662,7 +7893,7 @@ export interface TimeZoneNamedFromString extends decodeTo<TimeZoneNamed, String>
     readonly "Rebuild": TimeZoneNamedFromString;
 }
 /**
- * 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**
  *
@@ -7687,7 +7918,7 @@ export interface TimeZone extends declare<DateTime.TimeZone> {
     readonly "Rebuild": TimeZone;
 }
 /**
- * A schema for `DateTime.TimeZone` values.
+ * Schema for `DateTime.TimeZone` values.
  *
  * **Details**
  *
@@ -7711,7 +7942,7 @@ export interface TimeZoneFromString extends decodeTo<TimeZone, String> {
     readonly "Rebuild": TimeZoneFromString;
 }
 /**
- * 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**
  *
@@ -7736,7 +7967,7 @@ export interface DateTimeZoned extends declare<DateTime.Zoned> {
     readonly "Rebuild": DateTimeZoned;
 }
 /**
- * A schema for `DateTime.Zoned` values.
+ * Schema for `DateTime.Zoned` values.
  *
  * **Details**
  *
@@ -7762,7 +7993,7 @@ export interface DateTimeZonedFromString extends decodeTo<DateTimeZoned, String>
     readonly "Rebuild": DateTimeZonedFromString;
 }
 /**
- * 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**
  *
@@ -8066,9 +8297,12 @@ export declare const Class: {
     };
 };
 /**
- * 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**
  *
@@ -8094,9 +8328,12 @@ export declare const Class: {
  */
 export declare const TaggedClass: {
     /**
-     * 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**
      *
@@ -8122,9 +8359,12 @@ export declare const TaggedClass: {
      */
     <Self = never, Brand = {}>(identifier?: string): {
         /**
-         * 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**
          *
@@ -8150,9 +8390,12 @@ export declare const TaggedClass: {
          */
         <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedClass"> : Class<Self, TaggedStruct<Tag, Fields>, Brand>;
         /**
-         * 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**
          *
@@ -8282,9 +8525,13 @@ export declare const ErrorClass: {
     };
 };
 /**
- * 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)
  *
@@ -8305,9 +8552,13 @@ export declare const ErrorClass: {
  */
 export declare const TaggedErrorClass: {
     /**
-     * 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)
      *
@@ -8328,9 +8579,13 @@ export declare const TaggedErrorClass: {
      */
     <Self = never, Brand = {}>(identifier?: string): {
         /**
-         * 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)
          *
@@ -8351,9 +8606,13 @@ export declare const TaggedErrorClass: {
          */
         <Tag extends string, const Fields extends Struct.Fields>(tag: Tag, fields: Fields, annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedErrorClass"> : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>;
         /**
-         * 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)
          *
@@ -8424,7 +8683,7 @@ export declare function toArbitraryLazy<S extends Top>(schema: S): LazyArbitrary
  */
 export declare function toArbitrary<S extends Top>(schema: S): FastCheck.Arbitrary<S["Type"]>;
 /**
- * Annotates a schema with a custom formatter used by `toFormatter`.
+ * Attaches a custom formatter used by `toFormatter`.
  *
  * **Details**
  *
@@ -8454,8 +8713,12 @@ export declare function toFormatter<T>(schema: Schema<T>, options?: {
 }): Formatter<T>;
 /**
  * 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
@@ -8601,8 +8864,8 @@ export declare function toCodecIso<S extends Top>(schema: S): Codec<S["Type"], S
  */
 export type StringTree = Tree<string | undefined>;
 /**
- * The StringTree canonical codec converts **every leaf value to a string**, while
- * preserving the original structure.
+ * Converts a schema to the StringTree canonical codec, where every leaf value
+ * becomes a string while preserving the original structure.
  *
  * **Details**
  *
@@ -8682,12 +8945,19 @@ export interface overrideToCodecIso<S extends Top, Iso> extends Bottom<S["Type"]
     readonly schema: S;
 }
 /**
- * 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
  */