effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Schema.d.ts

@@ -153,7 +153,7 @@ export type ConstructorDefault = "no-default" | "with-default";
  *
  * **When to use**
  *
- * - Pass `disableChecks: true` to skip validation when you trust the data.
+ * Use when passing `disableChecks: true` to skip validation when you trust the data.
  * - Pass `parseOptions` to control error reporting behavior.
  *
  * @see {@link Bottom.makeEffect}
@@ -179,7 +179,7 @@ export interface MakeOptions {
  *
  * **When to use**
  *
- * - You are writing advanced generic schema utilities or performing schema
+ * Use when you are writing advanced generic schema utilities or performing schema
  *   introspection.
  * - In user code, prefer {@link Schema}, {@link Codec}, {@link Decoder}, or
  *   {@link Encoder} instead.
@@ -213,10 +213,57 @@ export interface Bottom<out T, out E, out RD, out RE, out Ast extends AST.AST, o
     check(...checks: readonly [AST.Check<this["Type"]>, ...Array<AST.Check<this["Type"]>>]): this["Rebuild"];
     rebuild(ast: this["ast"]): this["Rebuild"];
     /**
-     * Constructs a value from the make input representation.
+     * Constructs a value from the make input representation synchronously.
+     *
+     * **When to use**
+     *
+     * Use when constructor input is trusted or when validation failure
+     * should abort with a thrown `Error`.
+     *
+     * **Details**
+     *
+     * Applies constructor defaults and type-side validation according to
+     * `MakeOptions`.
+     *
+     * **Gotchas**
+     *
+     * Throws an `Error` with the schema issue in its `cause` when validation
+     * fails.
+     *
+     * @see {@link Bottom.makeOption} — construct synchronously and discard validation details
+     * @see {@link Bottom.makeEffect} — construct through `Effect` when validation failure should stay in the error channel
      */
     make(input: this["~type.make.in"], options?: MakeOptions): this["Type"];
+    /**
+     * Constructs a value from the make input representation, returning `Option.none`
+     * when validation fails.
+     *
+     * **When to use**
+     *
+     * Use when you only need to know whether construction succeeds
+     * and do not need validation details.
+     *
+     * **Details**
+     *
+     * Applies constructor defaults and type-side validation according to
+     * `MakeOptions`.
+     *
+     * @see {@link Bottom.make} — construct synchronously when validation failure should throw
+     * @see {@link Bottom.makeEffect} — construct through `Effect` when validation details should stay in the error channel
+     */
     makeOption(input: this["~type.make.in"], options?: MakeOptions): Option_.Option<this["Type"]>;
+    /**
+     * Constructs a value from the make input representation, returning validation
+     * failures in the `Effect` error channel.
+     *
+     * **When to use**
+     *
+     * Use when constructor input may fail validation and you want to
+     * compose that failure with other `Effect` operations instead of throwing.
+     *
+     * @see {@link Bottom.make} — construct synchronously when validation failure should throw
+     * @see {@link Bottom.makeOption} — construct synchronously and discard validation details
+     */
     makeEffect(input: this["~type.make.in"], options?: MakeOptions): Effect.Effect<this["Type"], SchemaError>;
 }
 /**
@@ -322,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**
@@ -695,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**
  *
@@ -843,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**
  *
@@ -889,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)
  *
@@ -921,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.
  *
@@ -934,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.
  *
@@ -946,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.
  *
@@ -959,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.
  *
@@ -971,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.
  *
@@ -985,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.
  *
@@ -995,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.
  *
@@ -1007,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.
  *
@@ -1017,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.
  *
@@ -1030,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.
  *
@@ -1044,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
@@ -1078,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.
@@ -1092,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.
  *
@@ -1116,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.
  *
@@ -1128,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.
  *
@@ -1141,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.
  *
@@ -1153,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.
  *
@@ -1167,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.
  *
@@ -1177,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.
  *
@@ -1189,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.
@@ -1199,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.
  *
@@ -1212,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.
  *
@@ -1222,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;
@@ -1236,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.
  *
@@ -1288,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
@@ -1337,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
@@ -1393,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
@@ -1427,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
@@ -1489,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)
  *
@@ -1651,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)
  *
@@ -1840,6 +2097,12 @@ export interface Boolean extends Bottom<boolean, boolean, never, never, AST.Bool
 /**
  * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
+ * **When to use**
+ *
+ * Use to validate values that are already JavaScript booleans.
+ *
+ * @see {@link BooleanFromBit} for a schema that decodes bit literals `0` or `1` into a boolean
+ *
  * @category Boolean
  * @since 4.0.0
  */
@@ -1873,6 +2136,13 @@ export interface BigInt extends Bottom<bigint, bigint, never, never, AST.BigInt,
 /**
  * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
+ * **When to use**
+ *
+ * Use when the input is already a bigint and the schema should validate and
+ * preserve bigint values without parsing from another representation.
+ *
+ * @see {@link BigIntFromString} for parsing string input into a bigint
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -2185,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)
  *
@@ -2440,6 +2718,14 @@ export declare namespace Record {
  * Companion type for a key-value record (map) with a typed key and value schema.
  * Produced by {@link Record}.
  *
+ * **When to use**
+ *
+ * Use as the concrete schema type returned by `Record` when an API needs to
+ * accept or return a record schema with typed property keys and values.
+ *
+ * @see {@link Record} for constructing record schemas
+ * @see {@link StructWithRest} for combining fixed struct fields with record index signatures
+ *
  * @category models
  * @since 4.0.0
  */
@@ -2570,6 +2856,14 @@ export declare namespace StructWithRest {
  * Companion type for a struct combined with one or more record schemas. Produced
  * by {@link StructWithRest}.
  *
+ * **When to use**
+ *
+ * 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
+ *
  * @category models
  * @since 4.0.0
  */
@@ -2911,17 +3205,22 @@ export declare function TupleWithRest<S extends Tuple<Tuple.Elements>, const Res
 /**
  * Schema interface produced by `Schema.Array` for readonly arrays.
  *
+ * **When to use**
+ *
+ * Use as the public companion type returned by `Schema.Array` when you need to
+ * refer to a readonly array schema built from an element schema.
+ *
  * **Details**
  *
  * The decoded type is `ReadonlyArray<S["Type"]>`, the encoded type is
  * `ReadonlyArray<S["Encoded"]>`, and the element schema is available as
- * `schema`.
+ * `value`.
  *
  * @category models
  * @since 4.0.0
  */
 export interface $Array<S extends Top> extends Bottom<ReadonlyArray<S["Type"]>, ReadonlyArray<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"], AST.Arrays, $Array<S>, ReadonlyArray<S["~type.make"]>, ReadonlyArray<S["Iso"]>> {
-    readonly schema: S;
+    readonly value: S;
 }
 interface ArrayLambda extends Lambda {
     <S extends Top>(self: S): $Array<S>;
@@ -2955,11 +3254,17 @@ ArraySchema as Array };
 /**
  * Companion type for a non-empty `ReadonlyArray`. Produced by {@link NonEmptyArray}.
  *
+ * **Details**
+ *
+ * The decoded type is `readonly [S["Type"], ...Array<S["Type"]>]`, the encoded type is
+ * `readonly [S["Encoded"], ...Array<S["Encoded"]>]`, and the element schema is available as
+ * `value`.
+ *
  * @category models
  * @since 3.10.0
  */
 export interface NonEmptyArray<S extends Top> extends Bottom<readonly [S["Type"], ...Array<S["Type"]>], readonly [S["Encoded"], ...Array<S["Encoded"]>], S["DecodingServices"], S["EncodingServices"], AST.Arrays, NonEmptyArray<S>, readonly [S["~type.make"], ...Array<S["~type.make"]>], readonly [S["Iso"], ...Array<S["Iso"]>]> {
-    readonly schema: S;
+    readonly value: S;
 }
 interface NonEmptyArrayLambda extends Lambda {
     <S extends Top>(self: S): NonEmptyArray<S>;
@@ -2988,12 +3293,19 @@ export declare const NonEmptyArray: NonEmptyArrayLambda;
  * Schema interface returned by `ArrayEnsure`, which normalizes a single item or
  * an array of items into a readonly array.
  *
+ * **When to use**
+ *
+ * Use as the schema type when generic code needs to retain the original item
+ * schema.
+ *
  * **Details**
  *
  * The schema decodes from `S` or `Schema.Array(S)` and produces
  * `ReadonlyArray<S["Type"]>`.
  *
- * @category Arrays
+ * @see {@link ArrayEnsure} for constructing this schema type
+ *
+ * @category constructors
  * @since 3.10.0
  */
 export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>, Union<readonly [S, $Array<S>]>> {
@@ -3003,16 +3315,26 @@ export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>,
  * Creates a schema that accepts either a value decoded by `schema` or an array
  * decoded by `Schema.Array(schema)`, then returns an array.
  *
+ * **When to use**
+ *
+ * Use to accept input that may be provided either as one item or as an array,
+ * while normalizing decoded values to a readonly array.
+ *
  * **Details**
  *
+ * During encoding, one-element arrays are encoded as the single element. Empty
+ * arrays and arrays with two or more elements are encoded as arrays.
+ *
+ * **Gotchas**
+ *
  * The single-value branch is tried before the array branch. If `schema` itself
  * accepts arrays, an array input can be treated as one value and wrapped in a
  * one-element array.
  *
- * During encoding, one-element arrays are encoded as the single element. Empty
- * arrays and arrays with two or more elements are encoded as arrays.
+ * @see {@link Array} for accepting only array input
+ * @see {@link NonEmptyArray} for requiring at least one decoded element
  *
- * @category Arrays
+ * @category constructors
  * @since 3.10.0
  */
 export declare function ArrayEnsure<S extends Top>(schema: S): ArrayEnsure<S>;
@@ -3278,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)
  *
@@ -3326,6 +3648,13 @@ type DistributeBrands<B> = UnionToIntersection<B extends infer U extends string
  * The output type of {@link brand}, intersecting the schema's `Type` with one or
  * more {@link Brand.Brand} tags.
  *
+ * **When to use**
+ *
+ * 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
+ *
  * @category branding
  * @since 3.10.0
  */
@@ -3337,6 +3666,18 @@ export interface brand<S extends Top, B> extends Bottom<S["Type"] & DistributeBr
  * Adds a nominal brand to a schema, intersecting the output type with
  * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
  *
+ * **When to use**
+ *
+ * Use to make values decoded by an existing schema nominally distinct when the
+ * schema already carries the runtime validation you need.
+ *
+ * **Gotchas**
+ *
+ * `brand` adds brand metadata and narrows the TypeScript output type, but it
+ * does not add runtime checks.
+ *
+ * @see {@link fromBrand} for applying a Brand constructor's checks along with the brand tag
+ *
  * @category branding
  * @since 3.10.0
  */
@@ -3457,7 +3798,20 @@ 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**
+ *
+ * Use when decoding fallback logic needs services from the Effect context.
+ *
+ * **Details**
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either succeeds
+ * with a fallback value or re-fails with a (possibly different) issue. The
+ * handler's services are added to the schema's decoding services.
+ *
+ * @see {@link catchDecoding} for recovery handlers that do not require services
+ * @see {@link middlewareDecoding} for intercepting or replacing the full decoding pipeline
  *
  * @category error handling
  * @since 4.0.0
@@ -3477,7 +3831,20 @@ 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**
+ *
+ * Use when encoding fallback logic needs services from the Effect context.
+ *
+ * **Details**
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either succeeds
+ * with a fallback encoded value or re-fails with a (possibly different) issue.
+ * The handler's services are added to the schema's encoding services.
+ *
+ * @see {@link catchEncoding} for recovery handlers that do not require services
+ * @see {@link middlewareEncoding} for intercepting or replacing the full encoding pipeline
  *
  * @category error handling
  * @since 4.0.0
@@ -3610,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)
  *
@@ -3941,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)
  *
@@ -3976,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**
  *
@@ -4625,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
@@ -4637,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
@@ -4649,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
@@ -4661,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
@@ -4673,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
@@ -4695,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
@@ -4913,9 +5294,9 @@ export declare function isDateValid(annotations?: Annotations.Filter): AST.Filte
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated Date objects are greater than the
- * specified value.
+ * When generating test data with fast-check, this applies a `min` constraint of
+ * one millisecond after the specified value to ensure generated Date objects are
+ * greater than it.
  *
  * @category Date checks
  * @since 4.0.0
@@ -4949,9 +5330,9 @@ export declare const isGreaterThanOrEqualToDate: (minimum: globalThis.Date, anno
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated Date objects are less than the
- * specified value.
+ * When generating test data with fast-check, this applies a `max` constraint of
+ * one millisecond before the specified value to ensure generated Date objects
+ * are less than it.
  *
  * @category Date checks
  * @since 4.0.0
@@ -4992,7 +5373,8 @@ export declare const isLessThanOrEqualToDate: (maximum: globalThis.Date, annotat
  * Arbitrary:
  *
  * When generating test data with fast-check, this applies `min` and `max`
- * constraints to ensure generated Date objects fall within the specified range.
+ * constraints to ensure generated Date objects fall within the specified range,
+ * shifting exclusive bounds by one millisecond.
  *
  * @category Date checks
  * @since 4.0.0
@@ -5010,8 +5392,8 @@ export declare const isBetweenDate: (options: {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated BigInts are greater than the
+ * When generating test data with fast-check, this applies a `min` constraint of
+ * `exclusiveMinimum + 1n` to ensure generated BigInts are greater than the
  * specified value.
  *
  * @category BigInt checks
@@ -5041,8 +5423,8 @@ export declare const isGreaterThanOrEqualToBigInt: (minimum: bigint, annotations
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated BigInts are less than the
+ * When generating test data with fast-check, this applies a `max` constraint of
+ * `exclusiveMaximum - 1n` to ensure generated BigInts are less than the
  * specified value.
  *
  * @category BigInt checks
@@ -5410,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
@@ -5428,7 +5810,20 @@ export interface Char extends String {
     readonly "Rebuild": Char;
 }
 /**
- * A schema representing a single character.
+ * Schema for strings whose JavaScript `length` is exactly `1`.
+ *
+ * **When to use**
+ *
+ * Use to validate string values that must have `length === 1`.
+ *
+ * **Gotchas**
+ *
+ * This schema uses JavaScript `String.length`, so visible characters made from
+ * multiple UTF-16 code units do not satisfy `length === 1`.
+ *
+ * @see {@link String} for unconstrained string values
+ * @see {@link NonEmptyString} for strings with length greater than zero
+ * @see {@link isLengthBetween} for the underlying length check
  *
  * @category String
  * @since 3.10.0
@@ -5476,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
@@ -5659,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>> {
@@ -5675,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> = {
@@ -5686,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>;
@@ -5704,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**
  *
@@ -5719,17 +6114,16 @@ export interface Redacted<S extends Top> extends declareConstructor<Redacted_.Re
  *   - The default JSON serializer will deserialize into a `Redacted` instance with the label
  *   - The arbitrary generator will produce a `Redacted` instance with the label
  *   - The formatter will return the label
- *
- * Default JSON serializer:
- *
- * The default JSON serializer will fail when attempting to serialize a `Redacted` value,
- * but it will deserialize a value into a `Redacted` instance.
+ * - `disallowJsonEncode`: When set to `true`, when attempting to encode a `Redacted` instance
+ *   into JSON, it will fail with an error. This is useful when the wrapped schema is
+ *   sensitive and should not be exposed in JSON.
  *
  * @category Redacted
  * @since 3.10.0
  */
 export declare function Redacted<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
+    readonly disallowJsonEncode?: boolean | undefined;
 }): Redacted<S>;
 /**
  * Type-level representation of a schema that decodes a raw value with the
@@ -5759,17 +6153,26 @@ export declare function redact<S extends Top>(schema: S): middlewareDecoding<S,
  */
 export declare function RedactedFromValue<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
+    readonly disallowEncode?: boolean | undefined;
 }): RedactedFromValue<S>;
 /**
  * Schema for a single `Cause.Reason`, representing one reason a fiber may fail:
  * a typed error (`Fail`), an unexpected defect (`Die`), or an interrupt
  * (`Interrupt`).
  *
+ * **When to use**
+ *
+ * Use as the schema type when generic code needs to retain the typed failure
+ * and defect schemas for a single cause reason.
+ *
  * **Details**
  *
  * The `error` schema validates typed failures and the `defect` schema validates
  * unexpected defects.
  *
+ * @see {@link CauseReason} for constructing this schema type
+ * @see {@link CauseReasonIso} for the ISO shape of each cause reason
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -5803,6 +6206,19 @@ export type CauseReasonIso<E extends Top, D extends Top> = {
  * Creates a schema for `Cause.Reason` values using separate schemas for typed
  * failures and unexpected defects.
  *
+ * **When to use**
+ *
+ * Use to validate, transform, or serialize individual `Cause.Reason` values
+ * when typed failures and unexpected defects need separate schemas.
+ *
+ * **Details**
+ *
+ * `Fail` reasons use the `error` schema, `Die` reasons use the `defect` schema,
+ * and `Interrupt` reasons carry only an optional fiber id.
+ *
+ * @see {@link Cause} for constructing schemas for full Cause values
+ * @see {@link CauseReasonIso} for the ISO shape of each cause reason
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -5811,11 +6227,19 @@ export declare function CauseReason<E extends Top, D extends Top>(error: E, defe
  * Schema for `Cause` values, represented as an ordered collection of failure
  * reasons combining typed errors, defects, and interrupts.
  *
+ * **When to use**
+ *
+ * Use as the schema type when generic code needs to retain the typed failure
+ * and defect schemas for a full cause.
+ *
  * **Details**
  *
  * The `error` schema validates typed failures and the `defect` schema validates
  * unexpected defects.
  *
+ * @see {@link Cause} for constructing this schema type
+ * @see {@link CauseIso} for the ordered array representation used by the schema ISO
+ *
  * @category Cause
  * @since 3.10.0
  */
@@ -5828,6 +6252,14 @@ export interface Cause<E extends Top, D extends Top> extends declareConstructor<
  * Iso representation used for `Cause` schemas: an ordered array of
  * `CauseReasonIso` values.
  *
+ * **When to use**
+ *
+ * Use when working with the ISO shape of a `Cause` schema, such as `toIso`
+ * optics or codecs that expose a cause as its ordered array of encoded reasons.
+ *
+ * @see {@link Cause} for constructing schemas for full Cause values
+ * @see {@link CauseReasonIso} for the ISO shape of each array element
+ *
  * @category Cause
  * @since 4.0.0
  */
@@ -5836,6 +6268,20 @@ export type CauseIso<E extends Top, D extends Top> = ReadonlyArray<CauseReasonIs
  * Creates a schema for `Cause` values using separate schemas for typed failures
  * and unexpected defects.
  *
+ * **When to use**
+ *
+ * Use to validate, transform, or serialize Effect failure causes when typed
+ * failures and unexpected defects need separate schemas.
+ *
+ * **Details**
+ *
+ * The `error` schema is applied to `Fail` reasons and the `defect` schema is
+ * applied to `Die` reasons. Interrupt reasons do not use either schema and
+ * carry only an optional fiber id.
+ *
+ * @see {@link CauseReason} for the schema used by each individual cause reason
+ * @see {@link CauseIso} for the ordered array representation used by the schema ISO
+ *
  * @category Cause
  * @since 3.10.0
  */
@@ -5850,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**
  *
@@ -5864,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**
@@ -5895,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**
@@ -5909,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
@@ -5959,6 +6404,15 @@ export declare function Exit<A extends Top, E extends Top, D extends Top>(value:
  * Type-level representation of a `ReadonlyMap` schema whose keys and values are
  * validated by the provided schemas.
  *
+ * **When to use**
+ *
+ * Use as a type annotation for a `ReadonlyMap` schema when exposing or returning
+ * the schema while preserving its key schema, value schema, and ISO
+ * representation.
+ *
+ * @see {@link ReadonlyMap} for constructing this schema type from key and value schemas
+ * @see {@link ReadonlyMapIso} for the readonly tuple-array ISO representation used by this schema
+ *
  * @category ReadonlyMap
  * @since 4.0.0
  */
@@ -5976,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
@@ -6004,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
@@ -6015,6 +6468,14 @@ export declare function HashMap<Key extends Top, Value extends Top>(key: Key, va
  * Type-level representation of a `ReadonlySet` schema whose values are validated
  * by the provided element schema.
  *
+ * **When to use**
+ *
+ * Use to name or constrain the schema type produced by `ReadonlySet` when
+ * generic code needs to retain the element schema type.
+ *
+ * @see {@link ReadonlySet} for constructing this schema type
+ * @see {@link ReadonlySetIso} for the array representation used by this schema's ISO
+ *
  * @category ReadonlySet
  * @since 4.0.0
  */
@@ -6031,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
@@ -6058,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
@@ -6080,13 +6539,19 @@ export interface Chunk<Value extends Top> extends declareConstructor<Chunk_.Chun
  * Iso representation used for `Chunk` schemas: an array of element values using
  * the element schema's `Iso` type.
  *
+ * **When to use**
+ *
+ * Use when annotating type-level helpers that work with the readonly-array ISO
+ * shape of a `Chunk` schema.
+ *
+ * @see {@link Chunk} for the schema interface and constructor that use this ISO representation
+ *
  * @category Chunk
  * @since 4.0.0
  */
 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
@@ -6122,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**
  *
@@ -6145,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**
  *
@@ -6170,14 +6635,18 @@ export interface Date extends instanceOf<globalThis.Date> {
     readonly "Rebuild": Date;
 }
 /**
- * A schema for JavaScript `Date` objects.
+ * Schema for JavaScript `Date` objects.
+ *
+ * **When to use**
+ *
+ * Use to validate in-memory values that must already be JavaScript `Date`
+ * instances.
  *
  * **Details**
  *
- * This schema accepts any `Date` instance, including invalid dates. For
- * validating only valid dates, use `DateValid` instead. The default JSON
- * serializer encodes valid dates as ISO 8601 strings; invalid dates encode as
- * `"Invalid Date"`.
+ * This schema accepts any `Date` instance, including invalid dates. The default
+ * JSON serializer encodes valid dates as ISO 8601 strings; invalid dates encode
+ * as `"Invalid Date"`.
  *
  * **Example** (Date schema)
  *
@@ -6188,6 +6657,8 @@ export interface Date extends instanceOf<globalThis.Date> {
  * // => Date { 2024-01-01T00:00:00.000Z }
  * ```
  *
+ * @see {@link DateValid} for accepting only valid Date instances
+ *
  * @category Date
  * @since 4.0.0
  */
@@ -6203,18 +6674,29 @@ 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**
+ *
+ * Use to model string-encoded dates that decode to JavaScript `Date` objects
+ * and encode back to strings.
  *
  * **Details**
  *
  * Decoding:
- * The string is passed to JavaScript `Date` construction and may decode to an
- * invalid `Date`. Compose with `DateValid` when invalid dates should be rejected.
+ * The string is passed to JavaScript `Date` construction.
  *
  * Encoding:
  * A valid `Date` is encoded as an ISO string; an invalid `Date` is encoded as
  * `"Invalid Date"`.
  *
+ * **Gotchas**
+ *
+ * Invalid date strings can decode to invalid `Date` instances.
+ *
+ * @see {@link Date} for accepting Date instances directly
+ * @see {@link DateValid} for rejecting invalid Date instances
+ *
  * @category Date
  * @since 3.10.0
  */
@@ -6230,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**
  *
@@ -6251,7 +6733,7 @@ export interface Duration extends declare<Duration_.Duration> {
     readonly "Rebuild": Duration;
 }
 /**
- * A schema for `Duration` values.
+ * Schema for `Duration` values.
  *
  * **Details**
  *
@@ -6283,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**
  *
@@ -6309,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**
@@ -6337,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.
  *
@@ -6365,7 +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 Effect decimal instances and need schema
+ * validation, formatting, equivalence, and JSON string serialization.
  *
  * **Details**
  *
@@ -6373,6 +6860,8 @@ export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
  *
  * - encodes `BigDecimal` as a `string`
  *
+ * @see {@link BigDecimalFromString} for parsing string input into a BigDecimal
+ *
  * @category BigDecimal
  * @since 3.10.0
  */
@@ -6388,15 +6877,28 @@ 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**
+ *
+ * Use to parse decimal or exponent-notation strings into arbitrary-precision
+ * BigDecimal values while encoding them back to strings.
  *
  * **Details**
  *
  * Decoding:
- * - A `string` is decoded as a `BigDecimal`.
+ * - A `string` is decoded with `BigDecimal.fromString`.
  *
  * Encoding:
- * - A `BigDecimal` is encoded as a `string`.
+ * - A `BigDecimal` is encoded with `BigDecimal.format`.
+ *
+ * **Gotchas**
+ *
+ * An empty string decodes as zero.
+ *
+ * @see {@link BigDecimal} for validating values that are already BigDecimal values
+ * @see {@link BigIntFromString} for parsing base-10 integer strings into bigint values
+ * @see {@link NumberFromString} for parsing JavaScript number strings
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -6413,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**
  *
@@ -6568,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**
  *
@@ -6686,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**
  *
@@ -6775,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
@@ -6792,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
@@ -6809,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**
@@ -6837,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**
  *
@@ -6863,7 +7369,12 @@ 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**
+ *
+ * Use to parse signed base-10 integer strings into bigint values while encoding
+ * bigint values back to decimal strings.
  *
  * **Details**
  *
@@ -6873,6 +7384,15 @@ export interface BigIntFromString extends decodeTo<BigInt, String> {
  * Encoding:
  * - A `bigint` is encoded as a `string`.
  *
+ * **Gotchas**
+ *
+ * Decoding accepts only strings matching `^-?\d+$`.
+ *
+ * @see {@link isStringBigInt} for the string predicate used by this schema
+ * @see {@link BigInt} for validating values that are already bigint values
+ * @see {@link NumberFromString} for parsing JavaScript number strings, including non-finite values
+ * @see {@link BigDecimalFromString} for parsing decimal number strings
+ *
  * @category BigInt
  * @since 4.0.0
  */
@@ -6888,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
@@ -6905,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**
  *
@@ -7039,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
@@ -7076,7 +7596,20 @@ 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**
+ *
+ * Use when decoding data sources that represent booleans as `0 | 1` while
+ * keeping boolean values in the decoded model.
+ *
+ * **Details**
+ *
+ * Decoding accepts only `0 | 1`, maps `1` to `true`, and maps `0` to `false`.
+ * Encoding maps `true` to `1` and `false` to `0`.
+ *
+ * @see {@link Boolean} for validating values that are already booleans
+ * @see {@link Literals} for keeping bit literals instead of decoding them
  *
  * @category Boolean
  * @since 4.0.0
@@ -7093,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**
  *
@@ -7116,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**
@@ -7142,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**
@@ -7168,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**
@@ -7194,13 +7727,22 @@ export interface DateTimeUtc extends declare<DateTime.Utc> {
     readonly "Rebuild": DateTimeUtc;
 }
 /**
- * A schema for `DateTime.Utc` values.
+ * Schema for `DateTime.Utc` values.
+ *
+ * **When to use**
+ *
+ * Use to validate existing `DateTime.Utc` schema values and use the default JSON
+ * codec that represents them as UTC ISO strings.
  *
  * **Details**
  *
- * Default JSON serializer:
+ * The default JSON codec decodes UTC ISO strings into `DateTime.Utc` values and
+ * encodes `DateTime.Utc` values as UTC ISO strings.
  *
- * - encodes `DateTime.Utc` as a UTC ISO string
+ * @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
+ * @see {@link DateTimeUtcFromDate} for decoding JavaScript Date values into UTC values
+ * @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
+ * @see {@link DateTimeZoned} for preserving zoned DateTime values
  *
  * @category DateTime
  * @since 3.10.0
@@ -7217,7 +7759,12 @@ 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**
+ *
+ * Use when a boundary provides valid JavaScript `Date` objects but the decoded
+ * model should use `DateTime.Utc`.
  *
  * **Details**
  *
@@ -7227,6 +7774,11 @@ export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
  * Encoding:
  * - A `DateTime.Utc` is encoded as a `Date`
  *
+ * @see {@link DateTimeUtc} for validating values that are already `DateTime.Utc`
+ * @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
+ * @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
+ * @see {@link DateValid} for validating Date instances without converting them
+ *
  * @category DateTime
  * @since 3.12.0
  */
@@ -7242,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**
  *
@@ -7270,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**
  *
@@ -7295,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**
  *
@@ -7318,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**
  *
@@ -7341,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**
  *
@@ -7366,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**
  *
@@ -7390,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**
  *
@@ -7415,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**
  *
@@ -7441,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**
  *
@@ -7501,13 +8053,23 @@ type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use
 /**
  * Creates a schema-backed class whose constructor validates input against a
  * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
- * input (unless `disableChecks` is set in the options).
+ * input.
+ *
+ * **When to use**
+ *
+ * Use to define a schema-backed data class when you want validated
+ * construction, schema-derived decoding/encoding, and class-style methods or
+ * inheritance.
  *
  * **Details**
  *
  * Pass the desired class type as the first type parameter. The second optional
  * type parameter can be used to add nominal brands.
  *
+ * **Gotchas**
+ *
+ * Passing `disableChecks` in the options skips constructor validation.
+ *
  * **Example** (Basic class)
  *
  * ```ts
@@ -7541,6 +8103,10 @@ type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use
  * console.log(dog.breed) // "Labrador"
  * ```
  *
+ * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+ * @see {@link ErrorClass} for defining schema-backed error classes
+ * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+ *
  * @category constructors
  * @since 3.10.0
  */
@@ -7548,13 +8114,23 @@ export declare const Class: {
     /**
      * Creates a schema-backed class whose constructor validates input against a
      * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-     * input (unless `disableChecks` is set in the options).
+     * input.
+     *
+     * **When to use**
+     *
+     * Use to define a schema-backed data class when you want validated
+     * construction, schema-derived decoding/encoding, and class-style methods or
+     * inheritance.
      *
      * **Details**
      *
      * Pass the desired class type as the first type parameter. The second optional
      * type parameter can be used to add nominal brands.
      *
+     * **Gotchas**
+     *
+     * Passing `disableChecks` in the options skips constructor validation.
+     *
      * **Example** (Basic class)
      *
      * ```ts
@@ -7588,6 +8164,10 @@ export declare const Class: {
      * console.log(dog.breed) // "Labrador"
      * ```
      *
+     * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+     * @see {@link ErrorClass} for defining schema-backed error classes
+     * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+     *
      * @category constructors
      * @since 3.10.0
      */
@@ -7595,13 +8175,23 @@ export declare const Class: {
         /**
          * Creates a schema-backed class whose constructor validates input against a
          * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-         * input (unless `disableChecks` is set in the options).
+         * input.
+         *
+         * **When to use**
+         *
+         * Use to define a schema-backed data class when you want validated
+         * construction, schema-derived decoding/encoding, and class-style methods or
+         * inheritance.
          *
          * **Details**
          *
          * Pass the desired class type as the first type parameter. The second optional
          * type parameter can be used to add nominal brands.
          *
+         * **Gotchas**
+         *
+         * Passing `disableChecks` in the options skips constructor validation.
+         *
          * **Example** (Basic class)
          *
          * ```ts
@@ -7635,6 +8225,10 @@ export declare const Class: {
          * console.log(dog.breed) // "Labrador"
          * ```
          *
+         * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+         * @see {@link ErrorClass} for defining schema-backed error classes
+         * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+         *
          * @category constructors
          * @since 3.10.0
          */
@@ -7642,13 +8236,23 @@ export declare const Class: {
         /**
          * Creates a schema-backed class whose constructor validates input against a
          * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-         * input (unless `disableChecks` is set in the options).
+         * input.
+         *
+         * **When to use**
+         *
+         * Use to define a schema-backed data class when you want validated
+         * construction, schema-derived decoding/encoding, and class-style methods or
+         * inheritance.
          *
          * **Details**
          *
          * Pass the desired class type as the first type parameter. The second optional
          * type parameter can be used to add nominal brands.
          *
+         * **Gotchas**
+         *
+         * Passing `disableChecks` in the options skips constructor validation.
+         *
          * **Example** (Basic class)
          *
          * ```ts
@@ -7682,6 +8286,10 @@ export declare const Class: {
          * console.log(dog.breed) // "Labrador"
          * ```
          *
+         * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+         * @see {@link ErrorClass} for defining schema-backed error classes
+         * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+         *
          * @category constructors
          * @since 3.10.0
          */
@@ -7689,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**
  *
@@ -7717,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**
      *
@@ -7745,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**
          *
@@ -7773,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**
          *
@@ -7905,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)
  *
@@ -7928,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)
      *
@@ -7951,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)
          *
@@ -7974,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)
          *
@@ -8047,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**
  *
@@ -8077,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
@@ -8116,7 +8756,7 @@ export declare function toRepresentation(schema: Top): SchemaRepresentation.Docu
 /**
  * Options for {@link toJsonSchemaDocument}.
  *
- * @category models
+ * @category JsonSchema
  * @since 4.0.0
  */
 export interface ToJsonSchemaOptions {
@@ -8137,6 +8777,54 @@ export interface ToJsonSchemaOptions {
      * provided them) based on the `expected` annotation of the check.
      */
     readonly generateDescriptions?: boolean | undefined;
+    /**
+     * A predicate that controls which additional annotation keys (beyond the
+     * standard JSON Schema keys) are included in the generated output.
+     *
+     * **When to use**
+     *
+     * Use when you need to include non-standard annotation keys in the generated
+     * JSON Schema, such as Monaco Editor properties (`markdownDescription`,
+     * `defaultSnippets`) or vendor extensions (`x-*`).
+     *
+     * **Details**
+     *
+     * Standard JSON Schema keys (`title`, `description`, `default`, `examples`,
+     * `readOnly`, `writeOnly`, `format`, `contentEncoding`, `contentMediaType`,
+     * `contentSchema`) are always included. This predicate is checked for any
+     * *other* annotation key.
+     *
+     * **Gotchas**
+     *
+     * Prefer whitelisting the custom annotation keys you want to emit instead of
+     * using a broad predicate such as `() => true`, because broad predicates can
+     * include Effect-specific annotations that are preserved for internal schema
+     * generation.
+     *
+     * **Example** (Including custom annotations)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const schema = Schema.String.annotate({
+     *   description: "A name",
+     *   markdownDescription: "The **name** field"
+     * })
+     *
+     * const doc = Schema.toJsonSchemaDocument(schema, {
+     *   includeAnnotationKey: (key) =>
+     *     key === "markdownDescription" || key.startsWith("x-")
+     * })
+     *
+     * console.log(doc.schema)
+     * // {
+     * //   type: "string",
+     * //   description: "A name",
+     * //   markdownDescription: "The **name** field"
+     * // }
+     * ```
+     */
+    readonly includeAnnotationKey?: ((key: string) => boolean) | undefined;
 }
 /**
  * Returns a JSON Schema document using draft 2020-12.
@@ -8176,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**
  *
@@ -8257,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
  */