effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/ai/Model.ts

@@ -1,53 +1,12 @@
 /**
- * The `Model` module wraps a provider-specific language model layer with the
- * metadata Effect AI needs at runtime. A `Model` is still a `Layer`, but it
- * also provides the current provider name and model name to programs that need
- * to inspect or report which model is in use.
- *
- * **Mental model**
- *
- * - `make` combines a provider identifier, a model identifier, and a layer that
- *   provides AI services such as `LanguageModel`.
- * - Providing the resulting model installs both the provider services and the
- *   metadata services {@link ProviderName} and {@link ModelName}.
- * - `captureRequirements` lets effectful setup capture the current environment
- *   into a concrete model layer.
- *
- * **Common tasks**
- *
- * - Create a provider-backed model with {@link make}.
- * - Provide the model to a program with `Effect.provide`.
- * - Read {@link ProviderName} and {@link ModelName} inside shared workflows,
- *   telemetry, or provider-agnostic services.
- *
- * **Gotchas**
- *
- * - The provider and model names are metadata; the actual implementation still
- *   comes from the layer passed to {@link make}.
- * - If the underlying layer has requirements, those requirements must be
- *   satisfied before the model can be provided.
- *
- * **Example** (Providing model metadata)
- *
- * ```ts
- * import { Effect } from "effect"
- * import type { Layer } from "effect"
- * import { LanguageModel, Model } from "effect/unstable/ai"
- *
- * declare const languageModelLayer: Layer.Layer<LanguageModel.LanguageModel>
- *
- * const model = Model.make("example-provider", "fast-text", languageModelLayer)
- *
- * const program = Effect.gen(function*() {
- *   const provider = yield* Model.ProviderName
- *   const modelName = yield* Model.ModelName
- *   const response = yield* LanguageModel.generateText({
- *     prompt: `Generate with ${provider}/${modelName}`
- *   })
- *
- *   return response.text
- * }).pipe(Effect.provide(model))
- * ```
+ * Wraps an AI model layer with provider and model metadata.
+ *
+ * A `Model` can be used anywhere its underlying `Layer` can be used. It also
+ * provides the current provider name and model name through the Effect context.
+ * This module includes the `Model` interface, the `ProviderName` and
+ * `ModelName` service tags, and the `make` constructor. Models can also capture
+ * their required services from the current context when they need to be used
+ * inside another Effect service.
  *
  * @since 4.0.0
  */

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -1,52 +1,12 @@
 /**
- * Adapt Effect Schema codecs to the JSON Schema subset accepted by OpenAI
- * structured output.
+ * Adapts Effect schemas for OpenAI structured output.
  *
- * The main entry point is {@link toCodecOpenAI}. It returns a JSON Schema value
- * for the model request and a codec that preserves the original decoded Type
- * while changing the encoded representation when OpenAI cannot express that
- * shape directly.
- *
- * **Mental model**
- *
- * OpenAI structured output requires a narrower schema vocabulary than Effect
- * Schema. This module walks the schema AST before JSON Schema generation,
- * rewrites unsupported shapes into OpenAI-compatible encodings, and
- * post-processes the generated JSON Schema to remove constructs such as
- * `allOf`.
- *
- * **Common tasks**
- *
- * - Convert a `Schema.Codec` for an OpenAI response format with
- *   {@link toCodecOpenAI}
- * - Decode model output back into the original application shape with the
- *   returned codec
- * - Represent optional properties as `T | null`, tuples as objects with
- *   numeric string keys, and records as arrays of `[key, value]` pairs
- *
- * **Gotchas**
- *
- * - The returned codec may encode to a different shape than the input schema,
- *   so use it for decoding model output instead of the original schema.
- * - Unsupported schema kinds throw during conversion rather than producing a
- *   lossy schema.
- * - Optional properties are required in the emitted JSON Schema and use `null`
- *   to represent absence because OpenAI requires object keys to be present.
- *
- * **Example** (Prepare a response schema)
- *
- * ```ts
- * import { Schema } from "effect"
- * import { OpenAiStructuredOutput } from "effect/unstable/ai"
- *
- * const Weather = Schema.Struct({
- *   city: Schema.String,
- *   forecast: Schema.optionalKey(Schema.String)
- * })
- *
- * const output = OpenAiStructuredOutput.toCodecOpenAI(Weather)
- * console.log(output.jsonSchema)
- * ```
+ * OpenAI structured output accepts only a subset of JSON Schema. This module
+ * converts an Effect `Schema.Codec` into a provider-compatible JSON Schema and
+ * a matching codec for decoding the model response back into the original
+ * application type. When possible, unsupported schema shapes are rewritten into
+ * supported ones; schema kinds that cannot be represented safely fail during
+ * conversion.
  *
  * @since 4.0.0
  */
@@ -331,8 +291,8 @@ function recurOpenAI(ast: SchemaAST.AST): SchemaAST.AST {
     case "Suspend": {
       const cached = cache.get(ast)
       if (cached) return cached
-      const { annotations, filters } = get(ast)
-      const out = new SchemaAST.Suspend(() => recurOpenAI(ast.thunk()), annotations, filters)
+      const { annotations } = get(ast)
+      const out = new SchemaAST.Suspend(() => recurOpenAI(ast.thunk()), annotations)
       cache.set(ast, out)
       return out
     }

package/src/unstable/ai/Prompt.ts

@@ -1,55 +1,11 @@
 /**
- * The `Prompt` module provides several data structures to simplify creating and
- * combining prompts.
+ * Defines prompts sent to AI language models.
  *
- * This module defines the complete structure of a conversation with a large
- * language model, including messages, content parts, and provider-specific
- * options. It supports rich content types like text, files, tool calls, and
- * reasoning.
- *
- * **Example** (Creating a structured conversation)
- *
- * ```ts
- * import { Prompt } from "effect/unstable/ai"
- *
- * // Create a structured conversation
- * const conversation = Prompt.make([
- *   {
- *     role: "system",
- *     content: "You are a helpful assistant specialized in mathematics."
- *   },
- *   {
- *     role: "user",
- *     content: [{
- *       type: "text",
- *       text: "What is the derivative of x²?"
- *     }]
- *   },
- *   {
- *     role: "assistant",
- *     content: [{
- *       type: "text",
- *       text: "The derivative of x² is 2x."
- *     }]
- *   }
- * ])
- * ```
- *
- * **Example** (Combining prompts)
- *
- * ```ts
- * import { Prompt } from "effect/unstable/ai"
- *
- * // Concatenate multiple prompts together sequentially
- * const systemPrompt = Prompt.make([{
- *   role: "system",
- *   content: "You are a coding assistant."
- * }])
- *
- * const userPrompt = Prompt.make("Help me write a function")
- *
- * const combined = Prompt.concat(systemPrompt, userPrompt)
- * ```
+ * A prompt is an ordered list of messages. Messages can use roles such as
+ * system, user, assistant, and tool, and their content can be split into typed
+ * parts such as text, files, reasoning, tool calls, tool results, and approval
+ * messages. This module helps build prompts, combine them, and convert raw
+ * input or response parts into the shared prompt shape.
  *
  * @since 4.0.0
  */

package/src/unstable/ai/Response.ts

@@ -1,53 +1,12 @@
 /**
- * The `Response` module defines Effect AI's provider-neutral representation of
- * model output. Text, reasoning, tool calls, tool results, files, source
- * citations, metadata, finish information, usage, and provider errors are all
- * modeled as typed response parts.
- *
- * **Mental model**
- *
- * - A response is an ordered sequence of parts.
- * - Non-streaming responses use complete parts such as `TextPart`,
- *   `ReasoningPart`, `ToolCallPart`, `ToolResultPart`, and `FinishPart`.
- * - Streaming responses use start, delta, and end parts for text, reasoning,
- *   and tool parameters before final tool-call or finish parts appear.
- * - Tool-aware schemas are built from a toolkit, so tool call parameters and
- *   tool result payloads stay aligned with each tool definition.
- *
- * **Common tasks**
- *
- * - Construct individual parts with {@link makePart}, {@link toolCallPart},
- *   {@link toolResultPart}, or {@link toolApprovalRequestPart}.
- * - Decode or encode parts with {@link Part}, {@link StreamPart}, or
- *   {@link AllParts}.
- * - Read completion metadata from {@link FinishPart}, {@link FinishReason},
- *   and {@link Usage}.
- *
- * **Gotchas**
- *
- * - `metadata` is reserved for provider-specific JSON and defaults to an empty
- *   object.
- * - Streaming text, reasoning, and tool parameter deltas are incremental events;
- *   accumulate them before treating them as final content.
- * - Tool result parts encode success and failure values according to the
- *   corresponding tool schemas.
- *
- * **Example** (Constructing response parts)
- *
- * ```ts
- * import { Response } from "effect/unstable/ai"
- *
- * const text = Response.makePart("text", {
- *   text: "The weather is sunny today."
- * })
- *
- * const toolCall = Response.toolCallPart({
- *   id: "call_123",
- *   name: "GetWeather",
- *   params: { city: "San Francisco" },
- *   providerExecuted: false
- * })
- * ```
+ * Defines a shared data model for AI model output.
+ *
+ * Responses are represented as typed parts so different providers can expose
+ * text, reasoning, tool calls, files, sources, metadata, finish information, and
+ * errors through one shape. The same model is used for complete responses and
+ * streaming responses, where start, delta, and end parts describe content as it
+ * arrives. This module also carries provider metadata and schemas used by tools
+ * that need to validate response parts.
  *
  * @since 4.0.0
  */

package/src/unstable/ai/ResponseIdTracker.ts

@@ -7,32 +7,6 @@
  * objects were included in each provider response and prepares a shorter prompt
  * when a later call extends the same conversation.
  *
- * **Mental model**
- *
- * The tracker is an optimization cache, not conversation storage. `markParts`
- * associates the exact message objects that were sent with the response ID the
- * provider returned. `prepareUnsafe` scans a future prompt, finds the latest
- * assistant-message boundary whose prefix is tracked, and returns that response
- * ID with only the messages after the boundary. If the prompt cannot be matched
- * safely, the cache is cleared and no incremental send is attempted.
- *
- * **Common tasks**
- *
- * - Provide `ResponseIdTracker` to a language model implementation that can use
- *   provider previous-response IDs
- * - Mark prompt messages after a successful provider response
- * - Prepare follow-up prompts so unchanged history is replaced by
- *   `previousResponseId`
- *
- * **Gotchas**
- *
- * - Tracking is based on object identity; equivalent message values are not
- *   recognized unless they are the same objects.
- * - The service is mutable and intentionally exposes `Unsafe` methods because
- *   callers coordinate it inside provider request/response code.
- * - A mismatch clears tracked state to avoid reusing a response ID for the
- *   wrong prompt prefix.
- *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"

package/src/unstable/ai/Telemetry.ts

@@ -1,35 +1,11 @@
 /**
- * OpenTelemetry span annotation helpers for Effect AI operations.
+ * Adds OpenTelemetry GenAI attributes to Effect AI spans.
  *
- * The `Telemetry` module models the OpenTelemetry GenAI semantic-convention
- * attributes used by language model and embedding providers, and exposes small
- * helpers for writing those attributes onto Effect tracing spans. It is used by
- * provider implementations and by applications that want consistent
- * `gen_ai.*` span metadata around model requests, responses, token usage, and
- * provider-specific identifiers.
- *
- * **Mental model**
- *
- * Attribute options are grouped by semantic-convention namespace: base
- * `gen_ai`, `operation`, `request`, `response`, `token`, and `usage`.
- * `addGenAIAnnotations` flattens those groups into span attributes, ignores
- * nullish values, and converts camelCase field names to snake_case keys.
- * `addSpanAttributes` provides the same prefix-and-transform behavior for
- * custom namespaces.
- *
- * **Common tasks**
- *
- * - Add standard GenAI attributes to the current span with
- *   `addGenAIAnnotations`.
- * - Create a custom attribute writer with `addSpanAttributes`.
- * - Provide `CurrentSpanTransformer` so a language model implementation can
- *   annotate the span after seeing the provider response.
- *
- * **Gotchas**
- *
- * These helpers annotate spans that already exist; they do not create or scope
- * spans. Attribute writers mutate the provided span, and only non-nullish
- * values are emitted.
+ * This module models the `gen_ai.*` attributes used by language model and
+ * embedding providers. It includes attribute types, helpers for writing
+ * non-null attributes onto existing spans, and a `CurrentSpanTransformer`
+ * service for adding custom span annotations from provider options and response
+ * parts.
  *
  * @since 4.0.0
  */

package/src/unstable/ai/Tokenizer.ts

@@ -1,50 +1,12 @@
 /**
- * Token counting and prompt truncation for AI integrations. A tokenizer is a
- * service because tokenization depends on the target model, provider, and
- * encoding rules rather than on Effect itself.
- *
- * **Mental model**
- *
- * {@link Tokenizer} provides two operations over prompt input: `tokenize`
- * converts a prompt into provider-specific token ids, and `truncate` keeps a
- * prompt within a token budget before it is sent to a model. Implementations
- * are usually provided by an AI provider package or by wrapping the tokenizer
- * used by the model.
- *
- * **Common tasks**
- *
- * - Count prompt tokens before choosing a model or request size
- * - Drop older conversation messages before a chat completion call
- * - Provide a custom tokenizer with {@link make} for tests or unsupported
- *   providers
- *
- * **Gotchas**
- *
- * - Token ids are model-specific. Counts from one tokenizer may not match
- *   another model's tokenizer.
- * - The `truncate` implementation produced by {@link make} keeps complete
- *   messages from the end of the prompt; it does not split a message to fit the
- *   remaining budget.
- * - Programs that access {@link Tokenizer} require a tokenizer service to be
- *   provided.
- *
- * **Example** (Providing a test tokenizer)
- *
- * ```ts
- * import { Effect } from "effect"
- * import { Tokenizer } from "effect/unstable/ai"
- *
- * const tokenizer = Tokenizer.make({
- *   tokenize: (prompt) =>
- *     Effect.succeed(prompt.content.map((_, index) => index))
- * })
- *
- * const program = Effect.gen(function*() {
- *   const service = yield* Tokenizer.Tokenizer
- *   const tokens = yield* service.tokenize("Count this prompt")
- *   return tokens.length
- * }).pipe(Effect.provideService(Tokenizer.Tokenizer, tokenizer))
- * ```
+ * Service for model-specific token counting and prompt truncation. Tokenization
+ * depends on the target provider, model, and encoding rules, so this module
+ * leaves the actual tokenization function to the service implementation.
+ *
+ * The `Tokenizer` service can count tokens for raw prompt input and shorten a
+ * prompt to a token limit by keeping the newest messages that fit. This module
+ * defines the service tag, the service interface, and a `make` constructor that
+ * builds a full tokenizer service from a token-counting function.
  *
  * @since 4.0.0
  */

package/src/unstable/ai/Tool.ts

@@ -1,58 +1,13 @@
 /**
- * The `Tool` module describes callable capabilities that a language model can
- * request during a workflow. A tool definition names the operation, describes
- * its parameter shape, declares the success and failure payloads, and carries
- * annotations that providers or MCP adapters can expose to clients.
- *
- * **Mental model**
- *
- * - `Tool.make` defines an application-owned tool whose handler is supplied by
- *   a toolkit.
- * - `dynamic` represents tools discovered at runtime, including tools backed by
- *   raw JSON Schema.
- * - `providerDefined` represents native provider features such as web search or
- *   code execution, optionally with an application handler for returned data.
- * - Schemas validate tool-call parameters and encode/decode handler results;
- *   `failureMode` controls whether handler failures fail the effect or become a
- *   returned tool-result value.
- *
- * **Common tasks**
- *
- * - Define typed application tools with {@link make}.
- * - Register runtime-discovered tools with {@link dynamic}.
- * - Model provider-native tools with {@link providerDefined}.
- * - Generate provider-facing parameter JSON Schema with {@link getJsonSchema}.
- * - Add tool metadata with annotations such as {@link Title}, {@link Readonly},
- *   {@link Destructive}, {@link Idempotent}, {@link OpenWorld}, and
- *   {@link Strict}.
- *
- * **Gotchas**
- *
- * - Tool names are runtime lookup keys for toolkits; choose stable names.
- * - Tool definitions do not execute anything by themselves. Handlers are bound
- *   when tools are placed in a toolkit.
- * - Dynamic tools created from raw JSON Schema receive `unknown` parameters in
- *   handlers. Use Effect `Schema` values when you need typed parameters.
- * - Provider-defined tools have both a custom Effect name and a provider name
- *   so multiple providers can expose similarly named native tools.
- *
- * **Example** (Defining a typed tool)
- *
- * ```ts
- * import { Schema } from "effect"
- * import { Tool } from "effect/unstable/ai"
- *
- * const SearchDocs = Tool.make("SearchDocs", {
- *   description: "Search project documentation",
- *   parameters: Schema.Struct({
- *     query: Schema.String,
- *     limit: Schema.optional(Schema.Number)
- *   }),
- *   success: Schema.Array(Schema.String),
- *   failure: Schema.String,
- *   needsApproval: ({ limit }) => limit !== undefined && limit > 20
- * }).annotate(Tool.Readonly, true)
- * ```
+ * Definitions and helpers for tools that AI models can request during a
+ * workflow.
+ *
+ * A tool names an operation, describes the parameters it accepts, declares
+ * successful and failed results, and can require approval before execution.
+ * This module supports tools defined by the application, tools built into a
+ * provider, and dynamic tools whose schema is known only at runtime. It also
+ * includes the shared types and conversion helpers needed by language-model
+ * requests, tool handlers, and provider integrations.
  *
  * @since 4.0.0
  */

package/src/unstable/ai/Toolkit.ts

@@ -1,80 +1,11 @@
 /**
- * The `Toolkit` module groups AI `Tool` definitions into a single typed service
- * that can execute tool calls by name. A toolkit is the runtime bridge between
- * declarative tool schemas and the handler functions your application provides
- * for a language model workflow.
+ * Groups AI tools together with their handlers.
  *
- * **Mental model**
- *
- * - A `Tool` describes one callable operation: its name, parameter schema,
- *   success schema, and failure behavior.
- * - A `Toolkit` is a record of tools that also carries the handler requirements
- *   needed to execute those tools.
- * - `toolkit.toLayer(...)` and `toolkit.toHandlers(...)` bind handlers into
- *   `Context`, so yielding a toolkit produces a value with a `handle` function.
- * - `handle` validates parameters, runs the matching handler, and returns a
- *   `Stream` of preliminary and final encoded results.
- *
- * **Common tasks**
- *
- * - Build a toolkit from tools: {@link make}
- * - Merge independently defined toolkits: {@link merge}
- * - Provide handlers with `toolkit.toLayer(...)` or `toolkit.toHandlers(...)`
- * - Emit progress from a long-running handler with `context.preliminary(...)`
- *
- * **Gotchas**
- *
- * - Tool names are runtime lookup keys. When toolkits are merged, later tools
- *   replace earlier tools with the same name.
- * - Handler output is validated and encoded against the tool schemas; invalid
- *   output is reported as an AI error.
- * - The result of `handle` is a stream because handlers can emit preliminary
- *   results before the final value.
- *
- * **Example** (Creating and implementing toolkits)
- *
- * ```ts
- * import { Effect, Schema, Stream } from "effect"
- * import { Tool, Toolkit } from "effect/unstable/ai"
- *
- * const GetCurrentTime = Tool.make("GetCurrentTime", {
- *   description: "Get the current timestamp",
- *   success: Schema.Number
- * })
- *
- * const GetWeather = Tool.make("GetWeather", {
- *   description: "Get weather for a location",
- *   parameters: Schema.Struct({ location: Schema.String }),
- *   success: Schema.Struct({
- *     temperature: Schema.Number,
- *     condition: Schema.String
- *   })
- * })
- *
- * const MyToolkit = Toolkit.make(GetCurrentTime, GetWeather)
- *
- * const MyToolkitLayer = MyToolkit.toLayer({
- *   GetCurrentTime: () => Effect.succeed(1_704_067_200_000),
- *   GetWeather: ({ location }) =>
- *     Effect.succeed({
- *       temperature: 72,
- *       condition: `sunny in ${location}`
- *     })
- * })
- *
- * const program = Effect.gen(function*() {
- *   const toolkit = yield* MyToolkit
- *   const stream = yield* toolkit.handle("GetWeather", {
- *     location: "San Francisco"
- *   })
- *   const results = yield* Stream.runCollect(stream)
- *
- *   return Array.from(results, ({ result }) => result)
- * }).pipe(Effect.provide(MyToolkitLayer))
- *
- * console.log(Effect.runSync(program))
- * // [{ temperature: 72, condition: "sunny in San Francisco" }]
- * ```
+ * A toolkit connects `Tool` schemas to the handler functions an application
+ * provides for a language model workflow. It can build a handler context or
+ * layer and execute tool calls by name. Execution validates parameters, runs the
+ * handler, encodes the result, supports preliminary streamed results, and
+ * applies the tool's failure mode.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/Argument.ts

@@ -1,25 +1,11 @@
 /**
- * The `Argument` module defines typed positional command-line arguments for
- * Effect CLI applications. Arguments consume ordered values after a command name
- * and its flags, then parse them into the types your command handler expects.
+ * Defines typed positional arguments for Effect CLI applications.
  *
- * Use this module for required inputs such as file paths, directories, numbers,
- * dates, choices, secrets, and structured configuration files. Arguments can be
- * made optional, variadic, validated with Schema, transformed with pure or
- * effectful functions, and supplied from defaults, config, or prompts when
- * missing.
- *
- * **Gotchas**
- *
- * - Positional arguments are order-sensitive; compose them in the same order the
- *   user should type them.
- * - `variadic` arguments can consume more than one value, so place them where
- *   the remaining positional input belongs.
- * - Use {@link withDescription} and {@link withMetavar} to keep generated help
- *   text clear, especially when the parser name differs from the value users
- *   should provide.
- * - Boolean positional arguments are intentionally not provided. Prefer boolean
- *   flags, or use {@link choice} for explicit `"true"` / `"false"` values.
+ * Arguments consume ordered values after a command name and its flags, then
+ * parse them into the types a command handler expects. This module includes
+ * constructors for common argument shapes, plus helpers for optional or
+ * variadic arguments, schema validation, transformations, defaults, config
+ * fallbacks, and prompts for missing values.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/CliError.ts

@@ -1,27 +1,12 @@
 /**
- * The `CliError` module defines the structured error model used by the
- * unstable CLI parser and runner. It distinguishes command-line parse failures,
- * CLI definition problems, explicit help requests, and user handler failures so
- * applications can report errors consistently while still pattern matching on
- * the exact cause.
- *
- * **Common tasks**
- *
- * - Detect CLI errors at runtime with {@link isCliError}
- * - Represent parse failures such as unknown flags, missing required inputs, or
- *   invalid argument values
- * - Attach parse or validation errors to {@link ShowHelp} when the runner should
- *   render help text together with the failure
- * - Preserve command handler failures with {@link UserError}
- *
- * **Gotchas**
- *
- * - {@link ShowHelp} is a control-flow error, not a parse failure; it exits with
- *   code `0` for explicit help and `1` when it carries errors
- * - Duplicate option names between parent and child commands are rejected
- *   because the parent command claims the flag before the child can see it
- * - Suggestion-bearing errors keep suggestions separate from the primary cause
- *   so help renderers can decide how much guidance to display
+ * Defines structured errors for the unstable CLI parser and runner.
+ *
+ * CLI errors describe problems such as unknown or duplicate flags, missing
+ * flags or arguments, invalid values, unknown subcommands, user handler
+ * failures, and requests to show command help. This module includes the
+ * `CliError` union, the `isCliError` guard, schema-backed error classes with
+ * display messages, and the `NonShowHelpErrors` union used when parse or
+ * validation errors should be shown with help output.
  *
  * @since 4.0.0
  */

package/src/unstable/cli/CliOutput.ts

@@ -1,24 +1,11 @@
 /**
- * The `CliOutput` module provides the formatting service used by Effect CLI
- * applications to turn parsed CLI metadata and failures into terminal text.
- * It renders help documents, parser errors, grouped errors, and version output,
- * while allowing applications and tests to replace the formatter through a
- * `Context` service or `Layer`.
+ * Formats CLI help and errors as text.
  *
- * **Common tasks**
- *
- * - Render generated {@link HelpDoc} values for `--help` output
- * - Display parser failures and validation errors from CLI programs
- * - Customize output for plain text, colored terminals, tests, or alternate
- *   formats
- * - Format version strings consistently with the rest of CLI output
- *
- * **Gotchas**
- *
- * - Color output is auto-detected from `process.stdout.isTTY` and `NO_COLOR`,
- *   but can be forced with {@link defaultFormatter}
- * - Help tables measure visible width after stripping ANSI escape codes, so
- *   colored output stays aligned with plain output
+ * This module turns help documents, CLI errors, grouped errors, and version
+ * information into strings. It does not write those strings to the terminal
+ * itself. It includes the `Formatter` interface, the formatter service, a layer
+ * for custom formatters, and the default formatter with configurable color
+ * support.
  *
  * @since 4.0.0
  */