effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -56,34 +56,36 @@ import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Rec from "../../Record.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import * as Tool from "./Tool.ts"
 
 /**
- * Transforms a `Schema.Codec` into a form compatible with OpenAI's structured output constraints.
+ * Converts a `Schema.Codec` to OpenAI structured-output JSON Schema and a
+ * matching codec for model output.
+ *
+ * **When to use**
+ *
+ * Use when you send Effect Schema-backed structured output requests to OpenAI
+ * and need provider-compatible JSON Schema without losing the decoded
+ * application type.
  *
  * **Details**
  *
- * The transformation walks the schema AST and rewrites constructs that
- * OpenAI does not support natively:
+ * Returns the JSON Schema to include in the request and the codec to use when
+ * decoding the model response. If the input schema already fits OpenAI's
+ * supported JSON Schema subset, the original codec is returned unchanged.
  *
- * - **Tuples** are converted to objects with numeric string keys (e.g.
- *   `"0"`, `"1"`) since OpenAI does not support tuple schemas. Rest
- *   elements are placed under a `"__rest__"` key.
- * - **Optional properties** are replaced with `T | null` unions, because
- *   OpenAI requires all properties to be present.
- * - **Records** (index signatures) are converted to arrays of `[key, value]`
- *   pairs.
- * - **`oneOf` unions** are rewritten as `anyOf` unions.
- * - **Regex patterns** from multiple filters are merged into a single
- *   `pattern` using lookaheads, since OpenAI does not support `allOf`.
- * - **Filters and annotations** are preserved where compatible (e.g.
- *   `description`, supported `format` values like `"date-time"`, `"email"`,
- *   `"uuid"`, etc.), and stripped otherwise.
+ * **Gotchas**
  *
- * If the schema is already compatible, the original codec is returned
- * unchanged.
+ * - Some schemas use a provider-safe encoded shape: tuples become objects with
+ *   numeric string keys, records become arrays of `[key, value]` pairs, and
+ *   optional properties become required nullable properties.
+ * - `oneOf` unions are emitted as `anyOf` unions.
+ * - Regex patterns from multiple filters are merged into one `pattern` because
+ *   OpenAI structured output does not support `allOf`.
+ * - Unsupported schema kinds throw during conversion instead of producing a
+ *   lossy schema.
  *
  * @category Codec Transformation
  * @since 4.0.0
@@ -95,8 +97,10 @@ export function toCodecOpenAI<T, E, RD, RE>(
   jsonSchema: JsonSchema.JsonSchema
 } {
   const to = schema.ast
-  const from = recurOpenAI(AST.toEncoded(to))
-  const codec = from === to ? schema : Schema.make<typeof schema>(AST.decodeTo(from, to, Transformation.passthrough()))
+  const from = recurOpenAI(SchemaAST.toEncoded(to))
+  const codec = from === to
+    ? schema
+    : Schema.make<typeof schema>(SchemaAST.decodeTo(from, to, SchemaTransformation.passthrough()))
   const document = JsonSchema.resolveTopLevel$ref(Schema.toJsonSchemaDocument(codec))
   const jsonSchema = rewriteOpenAI(document.schema)
   if (Object.keys(document.definitions).length > 0) {
@@ -136,7 +140,7 @@ function rewriteOpenAI(schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema {
   return out
 }
 
-function recurOpenAI(ast: AST.AST): AST.AST {
+function recurOpenAI(ast: SchemaAST.AST): SchemaAST.AST {
   switch (ast._tag) {
     case "Declaration":
     case "Void":
@@ -163,14 +167,14 @@ function recurOpenAI(ast: AST.AST): AST.AST {
     case "String": {
       const { annotations, filters } = get(ast)
       if (annotations !== undefined || filters !== undefined) {
-        return new AST.String(annotations, filters)
+        return new SchemaAST.String(annotations, filters)
       }
       return ast
     }
     case "Number": {
       const { annotations, filters } = get(ast)
       if (annotations !== undefined || filters !== undefined) {
-        return new AST.Number(annotations, filters)
+        return new SchemaAST.Number(annotations, filters)
       }
       return ast
     }
@@ -181,7 +185,7 @@ function recurOpenAI(ast: AST.AST): AST.AST {
       if (typeof literal === "string" || typeof literal === "number" || typeof literal === "boolean") {
         const { annotations, filters } = get(ast)
         if (annotations !== undefined || filters !== undefined) {
-          return new AST.Literal(ast.literal, annotations, filters)
+          return new SchemaAST.Literal(ast.literal, annotations, filters)
         }
         return ast
       }
@@ -193,12 +197,12 @@ function recurOpenAI(ast: AST.AST): AST.AST {
     }
     case "Union": {
       if (ast.mode === "oneOf") {
-        return new AST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
+        return new SchemaAST.Union(ast.types, "anyOf", ast.annotations, ast.checks)
       }
-      const types = AST.mapOrSame(ast.types, recurOpenAI)
+      const types = SchemaAST.mapOrSame(ast.types, recurOpenAI)
       const { annotations, filters } = get(ast)
       if (types !== ast.types || annotations !== undefined || filters !== undefined) {
-        return new AST.Union(types, "anyOf", annotations, filters)
+        return new SchemaAST.Union(types, "anyOf", annotations, filters)
       }
       return ast
     }
@@ -218,15 +222,17 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           annotations.description = TUPLE_DESCRIPTION
         }
         const propertySignatures = ast.elements.map((e, i) => {
-          return new AST.PropertySignature(String(i), e)
+          return new SchemaAST.PropertySignature(String(i), e)
         })
         if (ast.rest.length === 1) {
-          propertySignatures.push(new AST.PropertySignature(REST_PROPERTY_NAME, new AST.Arrays(false, [], ast.rest)))
+          propertySignatures.push(
+            new SchemaAST.PropertySignature(REST_PROPERTY_NAME, new SchemaAST.Arrays(false, [], ast.rest))
+          )
         }
-        return AST.decodeTo(
-          recurOpenAI(new AST.Objects(propertySignatures, [], annotations, filters)),
+        return SchemaAST.decodeTo(
+          recurOpenAI(new SchemaAST.Objects(propertySignatures, [], annotations, filters)),
           ast,
-          Transformation.transform({
+          SchemaTransformation.transform({
             decode: (o) => {
               let t: Array<unknown> = []
               for (let i = 0; i < ast.elements.length; i++) {
@@ -255,9 +261,9 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           })
         )
       } else {
-        const rest = AST.mapOrSame(ast.rest, recurOpenAI)
+        const rest = SchemaAST.mapOrSame(ast.rest, recurOpenAI)
         if (rest !== ast.rest || annotations !== undefined || filters !== undefined) {
-          return new AST.Arrays(false, [], rest, annotations, filters)
+          return new SchemaAST.Arrays(false, [], rest, annotations, filters)
         }
         return ast
       }
@@ -265,7 +271,7 @@ function recurOpenAI(ast: AST.AST): AST.AST {
     case "Objects": {
       let { annotations, filters } = get(ast)
       if (ast.indexSignatures.length === 0) {
-        const propertySignatures = AST.mapOrSame(ast.propertySignatures, (ps) => {
+        const propertySignatures = SchemaAST.mapOrSame(ast.propertySignatures, (ps) => {
           if (typeof ps.name !== "string") {
             throw new Error(
               `${errorPrefix}: Property names must be strings (got ${typeof ps.name})`
@@ -273,11 +279,11 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           }
           let type = recurOpenAI(ps.type)
           // optional properties are not supported by OpenAI, so we translate them to nullable unions
-          if (AST.isOptional(ps.type)) {
-            type = AST.decodeTo(
-              new AST.Union([type, AST.null], "anyOf"),
-              AST.optionalKey(type),
-              Transformation.transformOptional({
+          if (SchemaAST.isOptional(ps.type)) {
+            type = SchemaAST.decodeTo(
+              new SchemaAST.Union([type, SchemaAST.null], "anyOf"),
+              SchemaAST.optionalKey(type),
+              SchemaTransformation.transformOptional({
                 decode: Option.filter(Predicate.isNotNull),
                 encode: Option.orElseSome(() => null)
               })
@@ -286,12 +292,12 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           if (type === ps.type) {
             return ps
           }
-          return new AST.PropertySignature(ps.name, type)
+          return new SchemaAST.PropertySignature(ps.name, type)
         })
         if (
           propertySignatures !== ast.propertySignatures || annotations !== undefined || filters !== undefined
         ) {
-          return new AST.Objects(propertySignatures, [], annotations, filters)
+          return new SchemaAST.Objects(propertySignatures, [], annotations, filters)
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
@@ -305,10 +311,12 @@ function recurOpenAI(ast: AST.AST): AST.AST {
           annotations ??= {}
           annotations.description = RECORD_DESCRIPTION
         }
-        return AST.decodeTo(
-          recurOpenAI(new AST.Arrays(false, [], [new AST.Arrays(false, [is.parameter, is.type], [])], annotations)),
+        return SchemaAST.decodeTo(
+          recurOpenAI(
+            new SchemaAST.Arrays(false, [], [new SchemaAST.Arrays(false, [is.parameter, is.type], [])], annotations)
+          ),
           ast,
-          Transformation.transform({
+          SchemaTransformation.transform({
             decode: Object.fromEntries,
             encode: Object.entries
           })
@@ -324,18 +332,18 @@ function recurOpenAI(ast: AST.AST): AST.AST {
       const cached = cache.get(ast)
       if (cached) return cached
       const { annotations, filters } = get(ast)
-      const out = new AST.Suspend(() => recurOpenAI(ast.thunk()), annotations, filters)
+      const out = new SchemaAST.Suspend(() => recurOpenAI(ast.thunk()), annotations, filters)
       cache.set(ast, out)
       return out
     }
   }
 }
 
-const cache = new Map<AST.AST, AST.AST>()
+const cache = new Map<SchemaAST.AST, SchemaAST.AST>()
 
 const errorPrefix = "OpenAiStructuredOutput"
 
-function unsupportedAst(ast: AST.AST, details?: string): never {
+function unsupportedAst(ast: SchemaAST.AST, details?: string): never {
   const base = `Unsupported AST ${ast._tag}`
   const full = `${errorPrefix}: ${base}`
   throw new Error(details !== undefined ? `${full} (${details})` : full)
@@ -355,17 +363,17 @@ type Annotation =
 
 type Filter =
   | Annotation
-  | { readonly _tag: "filter"; readonly filter: AST.Filter<any> }
+  | { readonly _tag: "filter"; readonly filter: SchemaAST.Filter<any> }
   | { readonly _tag: "regex"; readonly source: string }
 
-const get = (ast: AST.AST): {
+const get = (ast: SchemaAST.AST): {
   annotations: Record<string, string> | undefined
-  filters: [AST.Check<any>, ...AST.Check<any>[]] | undefined
+  filters: [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]] | undefined
 } => {
   const annotations: Record<string, string> = {}
-  const filters: Array<AST.Filter<any>> = []
+  const filters: Array<SchemaAST.Filter<any>> = []
   const regexSources: Array<string> = []
-  const checks = getChecks(ast, AST.isArrays(ast))
+  const checks = getChecks(ast, SchemaAST.isArrays(ast))
   if (checks.length > 0) {
     for (const check of checks) {
       switch (check._tag) {
@@ -394,10 +402,10 @@ const get = (ast: AST.AST): {
   }
   // OpenAI does not support allOf, so we merge multiple regex patterns into a single isPattern filter
   if (regexSources.length === 1) {
-    filters.push(AST.isPattern(new RegExp(regexSources[0])))
+    filters.push(SchemaAST.isPattern(new RegExp(regexSources[0])))
   } else if (regexSources.length > 1) {
     const combined = regexSources.map((s) => `(?=[\\s\\S]*?(?:${s}))`).join("")
-    filters.push(AST.isPattern(new RegExp(`^${combined}`)))
+    filters.push(SchemaAST.isPattern(new RegExp(`^${combined}`)))
   }
   return {
     annotations: Object.keys(annotations).length > 0 ? annotations : undefined,
@@ -405,7 +413,7 @@ const get = (ast: AST.AST): {
   }
 }
 
-const getChecks = (ast: AST.AST, isArray: boolean): Array<Filter> => [
+const getChecks = (ast: SchemaAST.AST, isArray: boolean): Array<Filter> => [
   ...(ast.checks !== undefined ? getFilters(ast.checks, isArray) : []),
   ...getAnnotations(ast.annotations)
 ]
@@ -432,7 +440,7 @@ const getAnnotations = (annotations: Schema.Annotations.Filter | undefined): Arr
   return out
 }
 
-function getFilter(filter: AST.Filter<any>, isArray: boolean): Array<Filter> {
+function getFilter(filter: SchemaAST.Filter<any>, isArray: boolean): Array<Filter> {
   let out: Array<Filter> = []
   const annotations = getAnnotations(filter.annotations)
   const meta = filter.annotations?.meta
@@ -471,7 +479,7 @@ function getFilter(filter: AST.Filter<any>, isArray: boolean): Array<Filter> {
   return out
 }
 
-function resetFilter(filter: AST.Filter<any>): AST.Filter<any> {
+function resetFilter(filter: SchemaAST.Filter<any>): SchemaAST.Filter<any> {
   return filter.annotate({
     description: undefined,
     expected: undefined,
@@ -480,7 +488,10 @@ function resetFilter(filter: AST.Filter<any>): AST.Filter<any> {
   })
 }
 
-function getFilters(checks: readonly [AST.Check<any>, ...AST.Check<any>[]], isArray: boolean): Array<Filter> {
+function getFilters(
+  checks: readonly [SchemaAST.Check<any>, ...SchemaAST.Check<any>[]],
+  isArray: boolean
+): Array<Filter> {
   return checks.flatMap((check) => {
     switch (check._tag) {
       case "Filter":

package/src/unstable/ai/Prompt.ts

@@ -61,7 +61,7 @@ import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as SchemaIssue from "../../SchemaIssue.ts"
-import * as Parser from "../../SchemaParser.ts"
+import * as SchemaParser from "../../SchemaParser.ts"
 import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import type * as Response from "./Response.ts"
 
@@ -775,8 +775,8 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
  *
  * **When to use**
  *
- * Use when you use this part in tool messages to approve or deny tool execution when tools
- * have the `needsApproval` property set.
+ * Use when tool messages must approve or deny tool execution for tools with the
+ * `needsApproval` property set.
  *
  * **Example** (Creating tool approval responses)
  *
@@ -1783,7 +1783,7 @@ export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
     SchemaTransformation.transformOrFail({
       decode: (input) =>
         Effect.mapBothEager(
-          Parser.decodeEffect(Schema.Array(Message))(input.content),
+          SchemaParser.decodeEffect(Schema.Array(Message))(input.content),
           {
             onSuccess: makePrompt,
             onFailure: () =>
@@ -1792,7 +1792,7 @@ export const Prompt: Schema.Codec<Prompt, PromptEncoded> = Schema.Struct({
         ),
       encode: (prompt) =>
         Effect.mapBothEager(
-          Parser.encodeEffect(Schema.Array(Message))(prompt.content),
+          SchemaParser.encodeEffect(Schema.Array(Message))(prompt.content),
           {
             onSuccess: (messages) => ({ content: messages }),
             onFailure: () =>

package/src/unstable/ai/ResponseIdTracker.ts

@@ -83,8 +83,9 @@ export interface Service {
  *
  * **When to use**
  *
- * Use when when provided, language model operations can use the tracker to send only new
- * prompt messages together with the provider's prior response ID.
+ * Use when you provide a language model with previous-response ID tracking so
+ * later calls can send only new prompt messages together with the provider's
+ * prior response ID.
  *
  * @category services
  * @since 4.0.0

package/src/unstable/ai/Telemetry.ts

@@ -436,10 +436,15 @@ export type GenAITelemetryAttributeOptions = BaseAttributes & {
 /**
  * Applies GenAI telemetry attributes to an OpenTelemetry span.
  *
+ * **When to use**
+ *
+ * Use when you need to write GenAI request, response, token, or usage
+ * attributes onto an existing OpenTelemetry span.
+ *
  * **Details**
  *
- * This function adds standardized GenAI attributes to a span following OpenTelemetry
- * semantic conventions. It supports both curried and direct application patterns.
+ * This function adds standardized GenAI attributes to a span following
+ * OpenTelemetry semantic conventions.
  *
  * **Gotchas**
  *
@@ -469,10 +474,15 @@ export const addGenAIAnnotations: {
   /**
    * Applies GenAI telemetry attributes to an OpenTelemetry span.
    *
+   * **When to use**
+   *
+   * Use when you need to write GenAI request, response, token, or usage
+   * attributes onto an existing OpenTelemetry span.
+   *
    * **Details**
    *
-   * This function adds standardized GenAI attributes to a span following OpenTelemetry
-   * semantic conventions. It supports both curried and direct application patterns.
+   * This function adds standardized GenAI attributes to a span following
+   * OpenTelemetry semantic conventions.
    *
    * **Gotchas**
    *
@@ -502,10 +512,15 @@ export const addGenAIAnnotations: {
   /**
    * Applies GenAI telemetry attributes to an OpenTelemetry span.
    *
+   * **When to use**
+   *
+   * Use when you need to write GenAI request, response, token, or usage
+   * attributes onto an existing OpenTelemetry span.
+   *
    * **Details**
    *
-   * This function adds standardized GenAI attributes to a span following OpenTelemetry
-   * semantic conventions. It supports both curried and direct application patterns.
+   * This function adds standardized GenAI attributes to a span following
+   * OpenTelemetry semantic conventions.
    *
    * **Gotchas**
    *

package/src/unstable/ai/Tool.ts

@@ -63,7 +63,7 @@ import type * as JsonSchema from "../../JsonSchema.ts"
 import { pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
 import type * as Struct from "../../Struct.ts"
 import type * as Types from "../../Types.ts"
 import type * as AiError from "./AiError.ts"
@@ -1318,8 +1318,8 @@ export const make = <
  *
  * **When to use**
  *
- * Use when this is useful for tools where the schema isn't known at compile time,
- * such as MCP tools discovered at runtime or tools from external configurations.
+ * Use when you do not know a tool schema at compile time, such as MCP tools
+ * discovered at runtime or tools from external configurations.
  *
  * **Details**
  *
@@ -1363,8 +1363,8 @@ export const dynamic: {
    *
    * **When to use**
    *
-   * Use when this is useful for tools where the schema isn't known at compile time,
-   * such as MCP tools discovered at runtime or tools from external configurations.
+   * Use when you do not know a tool schema at compile time, such as MCP tools
+   * discovered at runtime or tools from external configurations.
    *
    * **Details**
    *
@@ -1681,7 +1681,7 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
     return tool.description
   }
   if (Schema.isSchema(tool.parametersSchema)) {
-    return AST.resolveDescription(tool.parametersSchema.ast)
+    return SchemaAST.resolveDescription(tool.parametersSchema.ast)
   }
   return undefined
 }
@@ -2028,7 +2028,8 @@ function filter(obj: any) {
  *
  * **When to use**
  *
- * Use when thrown parse and security failures are acceptable.
+ * Use when you need a JSON parser that throws for invalid JSON or unsafe
+ * object shapes.
  *
  * **Gotchas**
  *
@@ -2068,7 +2069,7 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
  *
  * **When to use**
  *
- * Use when a tool needs an explicit no-parameter `parameters` schema.
+ * Use when you need an explicit no-parameter `parameters` schema for a tool.
  *
  * **Details**
  *
@@ -2083,6 +2084,6 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
 export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)
 
 /** @internal */
-export function isEmptyParamsRecord(indexSignature: AST.IndexSignature): boolean {
-  return indexSignature.parameter === AST.string && AST.isNever(indexSignature.type)
+export function isEmptyParamsRecord(indexSignature: SchemaAST.IndexSignature): boolean {
+  return indexSignature.parameter === SchemaAST.string && SchemaAST.isNever(indexSignature.type)
 }

package/src/unstable/ai/Toolkit.ts

@@ -497,8 +497,8 @@ const resolveInput = <Tools extends ReadonlyArray<Tool.Any>>(
  *
  * **When to use**
  *
- * Use as a starting point for building toolkits or as a default value. Can
- * be extended using the merge function to add tools.
+ * Use when you need an empty starting point for building toolkits or a default
+ * toolkit value that can be extended with `merge`.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/cli/Command.ts

@@ -1484,8 +1484,8 @@ export const withAlias: {
  *
  * **When to use**
  *
- * Use when you use this for experimental or internal subcommands that should be accepted but
- * not advertised on the public CLI surface.
+ * Use when experimental or internal subcommands should be accepted but not advertised on
+ * the public CLI surface.
  *
  * **Example** (Hiding a subcommand)
  *
@@ -1600,7 +1600,8 @@ export const annotate: {
  *
  * **When to use**
  *
- * Use when attaching an already-built `Context.Context` of command annotations.
+ * Use when you need to attach an already-built `Context.Context` of command
+ * annotations.
  *
  * **Details**
  *
@@ -1623,7 +1624,8 @@ export const annotateMerge: {
    *
    * **When to use**
    *
-   * Use when attaching an already-built `Context.Context` of command annotations.
+   * Use when you need to attach an already-built `Context.Context` of command
+   * annotations.
    *
    * **Details**
    *
@@ -1648,7 +1650,8 @@ export const annotateMerge: {
    *
    * **When to use**
    *
-   * Use when attaching an already-built `Context.Context` of command annotations.
+   * Use when you need to attach an already-built `Context.Context` of command
+   * annotations.
    *
    * **Details**
    *
@@ -1916,6 +1919,11 @@ export const provide: {
  * Provides the handler of a command with the implementation of a service that
  * optionally depends on the command-line input to be constructed.
  *
+ * **When to use**
+ *
+ * Use when a command handler needs a pure service implementation, optionally
+ * derived from the parsed command input.
+ *
  * @category providing services
  * @since 4.0.0
  */
@@ -1924,6 +1932,11 @@ export const provideSync: {
    * Provides the handler of a command with the implementation of a service that
    * optionally depends on the command-line input to be constructed.
    *
+   * **When to use**
+   *
+   * Use when a command handler needs a pure service implementation, optionally
+   * derived from the parsed command input.
+   *
    * @category providing services
    * @since 4.0.0
    */
@@ -1934,6 +1947,11 @@ export const provideSync: {
    * Provides the handler of a command with the implementation of a service that
    * optionally depends on the command-line input to be constructed.
    *
+   * **When to use**
+   *
+   * Use when a command handler needs a pure service implementation, optionally
+   * derived from the parsed command input.
+   *
    * @category providing services
    * @since 4.0.0
    */
@@ -2123,9 +2141,8 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  *
  * **When to use**
  *
- * Use when you use `run` at an application entry point when arguments should come from
- * `Stdio`; use `runWith` when you need an explicit argument array, such as in
- * tests.
+ * Use when command-line arguments should come from `Stdio` at the application
+ * entry point.
  *
  * **Example** (Running commands with standard input)
  *
@@ -2146,6 +2163,8 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  * })
  * ```
  *
+ * @see {@link runWith} for running a command with an explicit argument array
+ *
  * @category command execution
  * @since 4.0.0
  */
@@ -2155,9 +2174,8 @@ export const run: {
    *
    * **When to use**
    *
-   * Use when you use `run` at an application entry point when arguments should come from
-   * `Stdio`; use `runWith` when you need an explicit argument array, such as in
-   * tests.
+   * Use when command-line arguments should come from `Stdio` at the application
+   * entry point.
    *
    * **Example** (Running commands with standard input)
    *
@@ -2178,6 +2196,8 @@ export const run: {
    * })
    * ```
    *
+   * @see {@link runWith} for running a command with an explicit argument array
+   *
    * @category command execution
    * @since 4.0.0
    */
@@ -2193,9 +2213,8 @@ export const run: {
    *
    * **When to use**
    *
-   * Use when you use `run` at an application entry point when arguments should come from
-   * `Stdio`; use `runWith` when you need an explicit argument array, such as in
-   * tests.
+   * Use when command-line arguments should come from `Stdio` at the application
+   * entry point.
    *
    * **Example** (Running commands with standard input)
    *
@@ -2216,6 +2235,8 @@ export const run: {
    * })
    * ```
    *
+   * @see {@link runWith} for running a command with an explicit argument array
+   *
    * @category command execution
    * @since 4.0.0
    */
@@ -2243,8 +2264,8 @@ export const run: {
  *
  * **When to use**
  *
- * Use when you use this function for testing CLI applications or when you want to
- * programmatically execute commands with specific arguments.
+ * Use when you need to test CLI applications or programmatically execute
+ * commands with specific arguments.
  *
  * **Example** (Running commands with explicit arguments)
  *

package/src/unstable/cli/Completions.ts

@@ -117,7 +117,7 @@ export type ArgumentType =
  *
  * **When to use**
  *
- * Use to produce an installable completion script when you already have a
+ * Use when you need an installable completion script from an existing
  * `CommandDescriptor`.
  *
  * **Details**