effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/cli/index.ts

@@ -5,21 +5,116 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 export * as Argument from "./Argument.ts"
 
 /**
+ * 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
+ *
  * @since 4.0.0
  */
 export * as CliError from "./CliError.ts"
 
 /**
+ * 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`.
+ *
+ * **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
+ *
  * @since 4.0.0
  */
 export * as CliOutput from "./CliOutput.ts"
 
 /**
+ * The `Command` module provides the core building block for defining and
+ * running Effect-based command-line applications. A `Command` combines a name,
+ * typed flags and positional arguments, optional subcommands, metadata for help
+ * output, and an effectful handler.
+ *
+ * **Common tasks**
+ *
+ * - Create commands with {@link make}
+ * - Add handlers with {@link withHandler}
+ * - Build nested command trees with {@link withSubcommands}
+ * - Share parent flags with subcommands using {@link withSharedFlags}
+ * - Add command-scoped global flags with {@link withGlobalFlags}
+ * - Attach help metadata with {@link withDescription}, {@link withShortDescription},
+ *   {@link withAlias}, and {@link withExamples}
+ * - Provide handler dependencies with {@link provide}, {@link provideSync},
+ *   {@link provideEffect}, and {@link provideEffectDiscard}
+ * - Execute commands with {@link run} or test them with {@link runWith}
+ *
+ * **Gotchas**
+ *
+ * - `withSharedFlags` accepts only flags, not positional arguments, and the
+ *   parsed values are available to descendants by yielding the parent command.
+ * - Shared flags may be written before or after the selected subcommand name.
+ * - Duplicate flags across command scopes are rejected so parsing and help
+ *   output remain unambiguous.
+ * - `runWith` is the preferred entry point for tests because it accepts an
+ *   explicit argument array instead of reading from the `Stdio` service.
+ *
  * @since 4.0.0
  */
 export * as Command from "./Command.ts"
@@ -32,30 +127,110 @@ export * as Command from "./Command.ts"
 export * as Completions from "./Completions.ts"
 
 /**
+ * The `Flag` module provides typed command-line options for Effect CLI
+ * applications. A `Flag<A>` describes how to read one named option from the
+ * parsed command line, validate it, and produce a value of type `A`.
+ *
+ * Use flags for inputs that are naturally named options, such as ports,
+ * verbosity switches, configuration files, output directories, enum-like
+ * choices, secrets, and repeated values. Constructors such as {@link string},
+ * {@link boolean}, {@link integer}, {@link file}, and {@link fileSchema}
+ * define the accepted input shape, while combinators add aliases, defaults,
+ * optionality, fallback config or prompts, validation, and typed mapping.
+ *
+ * Flag names are rendered as long options, for example `Flag.integer("port")`
+ * parses `--port 8080`. Boolean flags also support the disabled form shown by
+ * this module's boolean documentation, and repeated flags are modeled with the
+ * repetition combinators instead of by manually inspecting raw arguments. Help
+ * text is generated from flag metadata, so prefer {@link withDescription} and
+ * {@link withMetavar} when a flag's value, format, or file-system expectation
+ * would otherwise be ambiguous.
+ *
  * @since 4.0.0
  */
 export * as Flag from "./Flag.ts"
 
 /**
+ * The `GlobalFlag` module defines flags that are available to every command in
+ * an Effect CLI application. Global flags are useful for cross-cutting command
+ * line behavior such as printing help, showing the application version,
+ * generating shell completions, or configuring shared handler settings like the
+ * minimum log level.
+ *
+ * **Common tasks**
+ *
+ * - Create an action flag with {@link action} for side effects that should run
+ *   before the selected command, such as `--help` or `--version`
+ * - Create a setting flag with {@link setting} for values that should be made
+ *   available to command handlers through the Effect context
+ * - Reuse the built-in {@link Help}, {@link Version}, {@link Completions}, and
+ *   {@link LogLevel} flags when constructing command runners
+ *
+ * **Gotchas**
+ *
+ * - Action flags are intended to perform their effect and exit instead of
+ *   continuing into the command handler
+ * - Setting flags allocate a distinct context service for each call to
+ *   {@link setting}, so reuse exported settings when handlers need to read the
+ *   same parsed global value
+ *
  * @since 4.0.0
  */
 export * as GlobalFlag from "./GlobalFlag.ts"
 
 /**
+ * The `HelpDoc` module defines the structured documentation model used by the
+ * unstable CLI package to describe command help. A `HelpDoc` value captures the
+ * user-facing parts of a command, including its description, usage string,
+ * positional arguments, flags, global flags, subcommands, and examples.
+ *
+ * **Common tasks**
+ *
+ * - Build help data from command definitions before rendering it
+ * - Pass command documentation to `CliOutput.Formatter` implementations
+ * - Represent custom help output formats without changing command parsing
+ * - Group subcommands and distinguish local flags from global flags
+ *
+ * **Gotchas**
+ *
+ * - `HelpDoc` is format-agnostic; layout, ANSI styling, and table alignment are
+ *   handled by the output formatter
+ * - Optional argument and flag descriptions use `Option.Option<string>`, while
+ *   optional sections are omitted when they have no entries
+ * - Long names, aliases, and descriptions may require formatter-specific width
+ *   handling when rendering terminal help
+ *
  * @since 4.0.0
  */
 export * as HelpDoc from "./HelpDoc.ts"
 
 /**
- * @internal
+ * The `Param` module defines the shared parser tree used by the unstable CLI
+ * `Argument` and `Flag` modules. A `Param<Kind, A>` describes how to consume
+ * either positional arguments or named flags from parsed command-line input and
+ * return a typed value.
  *
- * Param is the polymorphic implementation shared by Argument.ts and Flag.ts.
- * The `Kind` type parameter ("argument" | "flag") enables type-safe separation
- * while sharing parsing logic and combinators.
+ * **Common tasks**
  *
- * Users should import from `Argument` and `Flag` modules, not this module directly.
- * This module is not exported from the public API.
+ * - Build primitive CLI inputs such as strings, booleans, numbers, choices,
+ *   paths, files, and redacted values
+ * - Attach help metadata with aliases and descriptions
+ * - Transform parsed values with pure or effectful validation
+ * - Model missing inputs with `Option`, defaults, config fallbacks, or prompts
+ * - Accept repeated inputs with variadic, bounded, and non-empty parameters
  *
+ * **Gotchas**
+ *
+ * - The `Kind` type parameter (`"argument"` or `"flag"`) keeps positional
+ *   arguments and flags separate while allowing the implementation and
+ *   combinators to be shared.
+ * - Combinators preserve the parameter kind, so an argument parameter cannot be
+ *   accidentally composed into a flag parameter or the reverse.
+ * - Parsers return both the remaining positional arguments and the parsed
+ *   value; this is important for argument ordering and variadic parameters.
+ * - Some parsers require CLI services such as filesystem, path, terminal, or
+ *   child-process support through the parsing environment.
+ * @internal
  * @since 4.0.0
  */
 export * as Param from "./Param.ts"
@@ -76,6 +251,30 @@ export * as Param from "./Param.ts"
 export * as Primitive from "./Primitive.ts"
 
 /**
+ * The `Prompt` module provides composable, effectful building blocks for
+ * interactive command-line questions. A `Prompt<A>` describes terminal UI that
+ * renders frames, reads keyboard input, validates responses, and eventually
+ * produces a value of type `A`.
+ *
+ * **Common tasks**
+ *
+ * - Ask for text, password, hidden, list, confirm, toggle, number, or date input
+ * - Let users choose from select, autocomplete, multi-select, and file prompts
+ * - Combine prompts with {@link all}, {@link map}, and {@link flatMap}
+ * - Build specialized prompts with {@link custom}
+ * - Run a prompt against the current terminal with {@link run}
+ *
+ * **Gotchas**
+ *
+ * - Prompts require terminal services and may fail with `Terminal.QuitError`
+ *   when input ends or the prompt is quit
+ * - Rendering is frame-based: custom prompts must return ANSI output from
+ *   `render` and matching ANSI clearing output from `clear`
+ * - Choices and file lists are paged by `maxPerPage`, so keyboard navigation
+ *   and filtering should account for hidden off-page entries
+ * - `password` and `hidden` return `Redacted` values; unwrap them only at the
+ *   boundary where the secret is needed
+ *
  * @since 4.0.0
  */
 export * as Prompt from "./Prompt.ts"

package/src/unstable/cli/internal/parser.ts

@@ -227,7 +227,6 @@ const makeCursor = (tokens: ReadonlyArray<Token>): TokenCursor => {
 
 /**
  * Creates a registry for O(1) flag lookup by name or alias.
- * @throws Error if duplicate names or aliases are detected (developer error)
  * @internal
  */
 export const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegistry => {

package/src/unstable/cluster/ClusterCron.ts

@@ -55,7 +55,7 @@ import * as Singleton from "./Singleton.ts"
  * scheduling step and optional controls for shard group, next-run calculation,
  * and skipping stale scheduled runs.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <E, R>(options: {

package/src/unstable/cluster/ClusterSchema.ts

@@ -39,7 +39,7 @@ import type { Request } from "./Envelope.ts"
  *
  * The default value is `false`.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchema/Persisted", {
@@ -50,7 +50,7 @@ export const Persisted = Context.Reference<boolean>("effect/cluster/ClusterSchem
  * Whether to wrap the request with a storage transaction, so sql queries are
  * committed atomically.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const WithTransaction = Context.Reference<boolean>(
@@ -66,7 +66,7 @@ export const WithTransaction = Context.Reference<boolean>(
  * handling only, `"server"` for server-side handling only, or `false` to allow
  * interruption.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
@@ -78,7 +78,7 @@ export const Uninterruptible = Context.Reference<boolean | "client" | "server">(
  * Returns whether the `Uninterruptible` annotation applies to server-side
  * request handling for the provided context.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const isUninterruptibleForServer = (context: Context.Context<never>): boolean => {
@@ -90,7 +90,7 @@ export const isUninterruptibleForServer = (context: Context.Context<never>): boo
  * Returns whether the `Uninterruptible` annotation applies to client-side
  * request handling for the provided context.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const isUninterruptibleForClient = (context: Context.Context<never>): boolean => {
@@ -103,7 +103,7 @@ export const isUninterruptibleForClient = (context: Context.Context<never>): boo
  *
  * By default, every entity id is assigned to the `"default"` shard group.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
@@ -117,7 +117,7 @@ export const ShardGroup = Context.Reference<(entityId: EntityId) => string>(
  *
  * The default value is `true`.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/ClusterSchema/ClientTracingEnabled", {
@@ -128,7 +128,7 @@ export const ClientTracingEnabled = Context.Reference<boolean>("effect/cluster/C
  * Dynamically transform the request annotations based on the request.
  * This only applies to the requests handled by the Entity, not the client.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const Dynamic = Context.Reference<

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -65,7 +65,7 @@ import * as Snowflake from "./Snowflake.ts"
  * Workflow executions, activities, deferred completions, resumes, interrupts,
  * and durable clock wakeups are coordinated through persisted cluster entities.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = Effect.gen(function*() {
@@ -726,7 +726,7 @@ const InterruptSignal = DurableDeferred.make("Workflow/InterruptSignal")
  * It requires cluster sharding and message storage, and also registers the
  * durable clock entity used for workflow wakeups.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layer: Layer.Layer<

package/src/unstable/cluster/Entity.ts

@@ -508,7 +508,6 @@ export interface Replier<Rpcs extends Rpc.Any> {
 /**
  * Helper types used by the `Replier` API.
  *
- * @category Replier
  * @since 4.0.0
  */
 export declare namespace Replier {

package/src/unstable/cluster/EntityProxy.ts

@@ -41,14 +41,11 @@ const clientErrors = [
 /**
  * Derives an `RpcGroup` from an `Entity`.
  *
+ * **Example** (Deriving RPC endpoints from an entity)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
- * import {
- *   ClusterSchema,
- *   Entity,
- *   EntityProxy,
- *   EntityProxyServer
- * } from "effect/unstable/cluster"
+ * import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
  * import { Rpc, RpcServer } from "effect/unstable/rpc"
  *
  * export const Counter = Entity.make("Counter", [
@@ -69,7 +66,7 @@ const clientErrors = [
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
@@ -109,6 +106,7 @@ export const toRpcGroup = <Type extends string, Rpcs extends Rpc.Any>(
  * For each entity RPC it creates a prefixed request RPC and a discard RPC whose
  * payload includes `entityId`, and whose errors include cluster client errors.
  *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs extends Rpc.Rpc<
@@ -158,14 +156,11 @@ const entityIdPath = {
 /**
  * Derives an `HttpApiGroup` from an `Entity`.
  *
+ * **Example** (Deriving HTTP API endpoints from an entity)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
- * import {
- *   ClusterSchema,
- *   Entity,
- *   EntityProxy,
- *   EntityProxyServer
- * } from "effect/unstable/cluster"
+ * import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
  * import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
  * import { Rpc } from "effect/unstable/rpc"
  *
@@ -193,7 +188,7 @@ const entityIdPath = {
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toHttpApiGroup = <const Name extends string, Type extends string, Rpcs extends Rpc.Any>(
@@ -237,6 +232,7 @@ const tagToPath = (tag: string): string =>
  * For each entity RPC it creates a POST endpoint at `/<tag>/:entityId` and a
  * discard endpoint at `/<tag>/:entityId/discard`, including cluster client errors.
  *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertHttpApi<Rpcs extends Rpc.Any> = Rpcs extends Rpc.Rpc<

package/src/unstable/cluster/EntityProxyServer.ts

@@ -39,7 +39,7 @@ import type { Sharding } from "./Sharding.ts"
  * request payload to the corresponding entity client method, including discard
  * endpoints.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttpApi = <
@@ -104,7 +104,7 @@ export const layerHttpApi = <
  * The handlers forward each prefixed proxy RPC to the target entity client using
  * the `entityId` embedded in the proxy payload.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerRpcHandlers = <
@@ -141,6 +141,7 @@ export const layerRpcHandlers = <
  *
  * Includes both the normal prefixed RPC handler and its discard variant.
  *
+ * @category services
  * @since 4.0.0
  */
 export type RpcHandlers<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs extends Rpc.Rpc<

package/src/unstable/cluster/EntityResource.ts

@@ -57,7 +57,7 @@ export type TypeId = "~effect/cluster/EntityResource"
  * `get` acquires or reuses the resource in the caller's scope, while `close`
  * invalidates it so its close scope can be released.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface EntityResource<out A, out E = never> {
@@ -89,7 +89,7 @@ export class CloseScope extends Context.Service<
  * By default, the `idleTimeToLive` is infinite, meaning the resource will only
  * be released when `close` is called.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make: <A, E, R>(options: {

package/src/unstable/cluster/Envelope.ts

@@ -37,7 +37,7 @@ import { type Snowflake, SnowflakeFromBigInt } from "./Snowflake.ts"
 /**
  * Type identifier used to mark runtime cluster envelope values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId = "~effect/cluster/Envelope"

package/src/unstable/cluster/HttpRunner.ts

@@ -53,7 +53,7 @@ import type * as ShardingConfig from "./ShardingConfig.ts"
  * The configured path is appended to each runner address, and `https` switches
  * the generated URL from `http` to `https`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerClientProtocolHttp = (options: {
@@ -84,7 +84,7 @@ export const layerClientProtocolHttp = (options: {
 /**
  * Default HTTP runner client protocol layer using path `/`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerClientProtocolHttpDefault: Layer.Layer<
@@ -100,7 +100,7 @@ export const layerClientProtocolHttpDefault: Layer.Layer<
  * The configured path is appended to each runner address, and `https` switches
  * the generated URL from `ws` to `wss`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerClientProtocolWebsocket = (options: {
@@ -133,7 +133,7 @@ export const layerClientProtocolWebsocket = (options: {
 /**
  * Default WebSocket runner client protocol layer using path `/`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerClientProtocolWebsocketDefault: Layer.Layer<
@@ -188,7 +188,7 @@ export const toHttpEffectWebsocket: Effect.Effect<
  * Layer that provides `Sharding` and `Runners` using the configured runner RPC
  * client protocol and storage services.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerClient: Layer.Layer<
@@ -203,7 +203,7 @@ export const layerClient: Layer.Layer<
  * A HTTP layer for the `Runners` services, that adds a route to the provided
  * `HttpRouter`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttpOptions = (options: {
@@ -227,7 +227,7 @@ export const layerHttpOptions = (options: {
  * WebSocket layer for the `Runners` services that adds a route to the provided
  * `HttpRouter`.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerWebsocketOptions = (options: {
@@ -253,7 +253,7 @@ export const layerWebsocketOptions = (options: {
  * It serves runner routes at `/` and configures runner clients to communicate
  * over HTTP.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttp: Layer.Layer<
@@ -276,7 +276,7 @@ export const layerHttp: Layer.Layer<
  * It configures runner clients to communicate over HTTP without serving runner
  * HTTP routes.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttpClientOnly: Layer.Layer<
@@ -297,7 +297,7 @@ export const layerHttpClientOnly: Layer.Layer<
  * It serves runner routes at `/` and configures runner clients to communicate
  * over WebSocket.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerWebsocket: Layer.Layer<
@@ -320,7 +320,7 @@ export const layerWebsocket: Layer.Layer<
  * It configures runner clients to communicate over WebSocket without serving
  * runner WebSocket routes.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerWebsocketClientOnly: Layer.Layer<

package/src/unstable/cluster/K8sHttpClient.ts

@@ -52,7 +52,7 @@ export class K8sHttpClient extends Context.Service<
  * bearer token when available, requires successful HTTP statuses, and retries
  * transient failures.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layer: Layer.Layer<
@@ -83,7 +83,7 @@ export const layer: Layer.Layer<
  * The request can be limited by namespace and label selector, and the result is a
  * map keyed by pod IP address.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const makeGetPods: (
@@ -130,7 +130,7 @@ export const makeGetPods: (
  * The pod defaults to the `default` namespace and is deleted when the surrounding
  * scope closes.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const makeCreatePod = Effect.gen(function*() {
@@ -234,7 +234,7 @@ export const makeCreatePod = Effect.gen(function*() {
 /**
  * Schema for the subset of Kubernetes Pod status used by cluster helpers.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export class PodStatus extends Schema.Class<PodStatus>("@effect/cluster/K8sHttpClient/PodStatus")({
@@ -253,7 +253,7 @@ export class PodStatus extends Schema.Class<PodStatus>("@effect/cluster/K8sHttpC
  *
  * The model exposes readiness helpers derived from the pod status conditions.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export class Pod extends Schema.Class<Pod>("@effect/cluster/K8sHttpClient/Pod")({

package/src/unstable/cluster/MachineId.ts

@@ -42,7 +42,7 @@ export type MachineId = typeof MachineId.Type
 /**
  * Brands a number as a `MachineId`.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = (id: number): MachineId => id as MachineId

package/src/unstable/cluster/MessageStorage.ts

@@ -211,7 +211,6 @@ export const SaveResultEncoded = Data.taggedEnum<SaveResult.Encoded>()
 /**
  * Variants and helper types for `SaveResult`.
  *
- * @category SaveResult
  * @since 4.0.0
  */
 export declare namespace SaveResult {
@@ -752,7 +751,7 @@ export const makeEncoded: (encoded: Encoded) => Effect.Effect<
 /**
  * No-op `MessageStorage` service that does not persist messages or replies.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const noop: MessageStorage["Service"] = Effect.runSync(make({