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

package/src/unstable/httpapi/HttpApi.ts

@@ -1,26 +1,50 @@
 /**
- * The `HttpApi` module defines the top-level contract for an Effect HTTP API.
- * An `HttpApi` names an API and collects one or more `HttpApiGroup`s, whose
- * endpoints describe the request inputs, response schemas, middleware, and
- * annotations that later drive server builders, clients, and OpenAPI
- * generation.
+ * The `HttpApi` module defines the top-level declaration for an Effect HTTP
+ * API. An {@link HttpApi} has an identifier, annotations, and a collection of
+ * groups whose endpoints describe request inputs, response schemas, middleware,
+ * and route metadata.
  *
- * Use this module when you want to compose a domain API from endpoint groups,
- * combine APIs from multiple modules, apply a shared path prefix or middleware,
- * attach annotations, or reflect over the final route shape. Implementations are
- * provided separately with `HttpApiBuilder.group`, and the completed API is
- * registered with `HttpApiBuilder.layer`.
+ * An `HttpApi` value is the shared contract consumed by server builders,
+ * generated clients, URL builders, OpenAPI generation, and reflection tools.
+ * Handler implementations are supplied later with `HttpApiBuilder.group`, and
+ * the completed API is registered with `HttpApiBuilder.layer`.
  *
- * A few composition details are worth keeping in mind: group identifiers are
- * used as keys, so adding another group with the same identifier replaces the
- * previous one; `prefix` and `middleware` are applied to the groups and
- * endpoints already present when they are called; and `addHttpApi` merges the
- * added API's annotations into its groups. During reflection, success and error
- * schemas are grouped by the HTTP status recorded on their `HttpApiSchema`
- * annotations, endpoints without an explicit success schema default to
- * `NoContent`, and middleware error schemas are included with endpoint errors.
- * Extra schemas supplied through `AdditionalSchemas` must have an `identifier`
- * annotation so they can be emitted as OpenAPI components.
+ * **Mental model**
+ *
+ * - {@link make} creates an empty API declaration with a stable identifier.
+ * - Groups are added to the API declaration, and each group owns its endpoint
+ *   declarations.
+ * - API-level prefixes, middleware, and annotations are composition operations
+ *   over the groups already present in the declaration.
+ * - {@link reflect} walks the final group and endpoint metadata with merged
+ *   annotations, status-indexed response schemas, and middleware errors.
+ *
+ * **Common tasks**
+ *
+ * - Create an API with {@link make}.
+ * - Add groups with the `add` method, or merge another API with `addHttpApi`.
+ * - Apply a shared path prefix, middleware, or annotation through the methods on
+ *   {@link HttpApi}.
+ * - Inspect the resulting route shape with {@link reflect}.
+ * - Register extra OpenAPI component schemas through {@link AdditionalSchemas}.
+ *
+ * **Gotchas**
+ *
+ * - Group identifiers are used as keys. Adding a group with the same identifier
+ *   replaces the previous group.
+ * - `prefix` and `middleware` affect the groups and endpoints already present
+ *   when those methods are called.
+ * - `addHttpApi` merges the added API's annotations into its groups.
+ * - Reflection includes middleware error schemas with endpoint errors and treats
+ *   endpoints without an explicit success schema as `NoContent`.
+ * - Schemas supplied through {@link AdditionalSchemas} must have an `identifier`
+ *   annotation so OpenAPI generation can emit them as components.
+ *
+ * **See also**
+ *
+ * - {@link make} for constructing API declarations.
+ * - {@link reflect} for inspecting groups and endpoints.
+ * - {@link AdditionalSchemas} for OpenAPI component schemas.
  *
  * @since 4.0.0
  */
@@ -54,7 +78,7 @@ export const isHttpApi = (u: unknown): u is Any => Predicate.hasProperty(u, Type
  *
  * **When to use**
  *
- * Endpoint implementations can be provided with `HttpApiBuilder.group`, and the
+ * Use when endpoint implementations can be provided with `HttpApiBuilder.group`, and the
  * completed API can be registered with `HttpApiBuilder.layer`.
  *
  * @category models
@@ -212,7 +236,7 @@ const makeProto = <Id extends string, Groups extends HttpApiGroup.Any>(
  *
  * **When to use**
  *
- * Add groups with `add` or `addHttpApi`, provide endpoint implementations with
+ * Use when add groups with `add` or `addHttpApi`, provide endpoint implementations with
  * `HttpApiBuilder.group`, and register the API with `HttpApiBuilder.layer`.
  *
  * @category constructors
@@ -226,14 +250,14 @@ export const make = <const Id extends string>(identifier: Id): HttpApi<Id, never
   })
 
 /**
- * Walks the groups and endpoints in an `HttpApi`.
+ * Describes the groups and endpoints in an `HttpApi`.
  *
  * **Details**
  *
  * The callbacks receive each group or endpoint with merged annotations, endpoint
  * middleware, and response schemas grouped by HTTP status.
  *
- * @category Reflection
+ * @category reflection
  * @since 4.0.0
  */
 export const reflect = <Id extends string, Groups extends HttpApiGroup.Any>(

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -1,30 +1,44 @@
 /**
- * The `HttpApiBuilder` module connects declarative `HttpApi` definitions to
- * runnable HTTP server routes.
+ * Server builders for declarative `HttpApi` contracts.
  *
- * Use this module when you have described an API with `HttpApi`,
- * `HttpApiGroup`, and `HttpApiEndpoint` values and need to provide the
- * server-side implementation. `group` creates a layer for implementing every
- * endpoint in one API group, `layer` registers the implemented groups with an
- * `HttpRouter` and can expose the generated OpenAPI specification, and
- * `endpoint` builds the effect for a single endpoint when custom composition is
- * needed.
+ * This module is the server-side bridge between an `HttpApi` description and an
+ * `HttpRouter`. It turns endpoint metadata into routes, decodes incoming
+ * request parts with `Schema`, runs HTTP API middleware, invokes the registered
+ * handlers, and encodes successes or declared errors back into
+ * `HttpServerResponse` values.
  *
- * The builder performs the runtime work implied by endpoint metadata: it decodes
- * path parameters, headers, query parameters, and request payloads with
- * `Schema`, applies endpoint middleware and security middleware, invokes the
- * registered handler, and encodes successful or declared error results into
- * `HttpServerResponse` values. Handlers can return an `HttpServerResponse`
- * directly to bypass success encoding, and `handleRaw` can be used when payload
- * decoding should be handled manually.
+ * **Mental model**
  *
- * A few implementation details are worth keeping in mind. Every group in the
- * API must be provided with `HttpApiBuilder.group` before `layer` is evaluated,
- * otherwise registration fails with a defect that names the missing group and
- * the available group services. Payload decoding is selected by request media type;
- * unsupported content types produce a `415` response before the handler runs.
- * Schema failures are wrapped as `HttpApiSchemaError`, while ordinary handler
- * failures are encoded with the endpoint's declared error schemas.
+ * `HttpApi` values describe what can be served; this module supplies how it is
+ * served. Implement each group with {@link group}, then register the completed
+ * API with {@link layer}. The layer reads the group implementations from the
+ * Effect context, adds their routes to the active `HttpRouter`, and can also
+ * expose the generated OpenAPI document.
+ *
+ * **Common tasks**
+ *
+ * Use {@link group} with `handlers.handle` to implement every endpoint in one
+ * API group. Use `handlers.handleRaw` when the handler needs direct access to
+ * the `HttpServerRequest` or must decode the payload manually. Use
+ * {@link endpoint} when composing one endpoint route by hand, and use
+ * {@link securityDecode} or {@link securitySetCookie} inside security-aware
+ * middleware.
+ *
+ * **Gotchas**
+ *
+ * Every group in the API must have a matching {@link group} layer before
+ * {@link layer} is evaluated; otherwise registration fails with a defect naming
+ * the missing group service. Payload decoding is selected from the request
+ * media type, so unsupported content types return `415` before the handler
+ * runs. Request decoding failures are wrapped in `HttpApiSchemaError`; handler
+ * failures are encoded only when they match the endpoint or middleware error
+ * schemas.
+ *
+ * **See also**
+ *
+ * `HttpApi` for the top-level contract, `HttpApiGroup` and `HttpApiEndpoint`
+ * for declaration, `HttpApiMiddleware` for server and client middleware, and
+ * `OpenApi` for generated specifications.
  *
  * @since 4.0.0
  */
@@ -71,7 +85,7 @@ import type * as HttpApiSecurity from "./HttpApiSecurity.ts"
 import * as OpenApi from "./OpenApi.ts"
 
 /**
- * Register an `HttpApi` with a `HttpRouter`.
+ * Registers an `HttpApi` with a `HttpRouter`.
  *
  * @category constructors
  * @since 4.0.0
@@ -172,7 +186,7 @@ export const group = <
 /**
  * Type identifier symbol used to brand `Handlers` values.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export const HandlersTypeId: unique symbol = Symbol.for("@effect/platform/HttpApiBuilder/Handlers")
@@ -180,7 +194,7 @@ export const HandlersTypeId: unique symbol = Symbol.for("@effect/platform/HttpAp
 /**
  * Type of the `Handlers` type identifier symbol.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export type HandlersTypeId = typeof HandlersTypeId

package/src/unstable/httpapi/HttpApiClient.ts

@@ -1,24 +1,36 @@
 /**
- * Builds type-safe clients and URL builders from `HttpApi` declarations.
+ * Type-safe HTTP clients derived from `HttpApi` declarations.
  *
  * This module turns the groups and endpoints described by an `HttpApi` into
- * callable client methods backed by an `HttpClient`. Applications commonly use
- * `make` or `makeWith` to call a remote API with the same schema-driven contract
- * as the server, while `group`, `endpoint`, and `urlBuilder` are useful when only
- * part of an API or only the encoded URL is needed.
+ * callable client methods backed by an `HttpClient`. Use {@link make} or
+ * {@link makeWith} to call a remote API with the same schema-driven contract as
+ * the server, and use {@link group}, {@link endpoint}, or {@link urlBuilder}
+ * when only part of an API or only the encoded URL is needed.
  *
- * Client calls encode path parameters, query values, headers, and payloads from
- * endpoint schemas before executing the request, then decode successful responses
- * according to the endpoint success schemas. The selected `responseMode` can
- * return the decoded value, the raw `HttpClientResponse`, or both; the raw
- * response mode skips success and error decoding for custom response handling.
+ * **Mental model**
  *
- * Pay attention to the endpoint schemas when shaping requests: payloads for HTTP
- * methods without request bodies are encoded into URL parameters, multipart
- * payloads must be supplied as `FormData`, and response decoding can fail with
- * `SchemaError`. Declared error responses are decoded into the endpoint error
- * type, unknown statuses fail as `HttpClientError.DecodeError`, and failures while
- * decoding a declared error response include the original status-code failure.
+ * A generated client mirrors the API structure: top-level endpoints become
+ * methods on the client, and named groups become nested objects. Each call
+ * encodes path parameters, query values, headers, and payloads from endpoint
+ * schemas, runs client middleware, executes the request, and decodes successful
+ * or declared error responses from the returned `HttpClientResponse`.
+ *
+ * **Common tasks**
+ *
+ * Use {@link make} when the `HttpClient` service should come from the Effect
+ * environment. Use {@link makeWith} when a concrete or transformed client is
+ * already available. Use {@link urlBuilder} to reuse endpoint path and query
+ * encoding without executing a request. Select `responseMode` per call when
+ * code needs the decoded value, the raw response, or both.
+ *
+ * **Gotchas**
+ *
+ * Payloads for HTTP methods without request bodies are encoded into URL
+ * parameters, and multipart payloads must be supplied as `FormData`.
+ * `response-only` skips success and error decoding for custom response
+ * handling. Declared error responses decode into the endpoint error type;
+ * unknown statuses fail as `HttpClientError.DecodeError`, and response decoding
+ * can fail with `SchemaError`.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -1,27 +1,55 @@
 /**
- * The `HttpApiEndpoint` module defines the per-route contracts used inside an
- * `HttpApiGroup`.
- *
- * An endpoint couples a stable name with an HTTP method and `HttpRouter` path,
- * plus schemas for path parameters, query parameters, headers, request payloads,
- * success responses, and declared errors. Server builders, generated clients,
- * and OpenAPI generation all read this metadata to decode requests, encode
- * responses, type handler inputs, and derive client call signatures.
- *
- * Use this module to declare individual operations such as `get`, `post`, `put`,
- * `patch`, `delete`, `head`, and `options`; attach endpoint-specific middleware
- * or annotations; and model alternatives for payloads, successes, and errors
- * with arrays of schemas.
- *
- * A few declaration details are worth keeping in mind. Paths use
- * `HttpRouter.PathInput`, so route parameters come from the router and are
- * decoded with the optional `params` schema. When codecs are enabled, params,
- * query, and headers are transformed through string-tree codecs; body methods
- * use JSON payload codecs by default, while no-body methods encode payloads as
- * query-style values. `HttpApiSchema` annotations can change payload or response
- * encodings and status codes, multipart payloads cannot be combined under the
- * same content type, and endpoint errors are merged with middleware errors for
- * server encoding and client decoding.
+ * The `HttpApiEndpoint` module defines the route-level contracts used inside an
+ * HTTP API group. An endpoint records a stable name, HTTP method, router path,
+ * request schemas, response schemas, declared errors, middleware, and
+ * annotations.
+ *
+ * Endpoint values are declarations, not handlers. Builders use them to decode
+ * requests, type handler input, encode responses, generate OpenAPI metadata,
+ * and derive generated-client call signatures.
+ *
+ * **Mental model**
+ *
+ * - Each {@link HttpApiEndpoint} describes one HTTP route.
+ * - Method constructors such as {@link get}, {@link post}, {@link put},
+ *   {@link patch}, {@link head}, and {@link options} create endpoint
+ *   declarations. Use {@link make} when you need a method-specific constructor.
+ * - Params, query, headers, payload, success, and error schemas determine both
+ *   runtime encoding/decoding and the exported helper types such as
+ *   {@link Request}, {@link ClientRequest}, {@link Success}, and {@link Error}.
+ * - Endpoint middleware and annotations are stored on the declaration so server
+ *   builders, clients, and OpenAPI generation can see the same route metadata.
+ *
+ * **Common tasks**
+ *
+ * - Declare operations with {@link get}, {@link post}, {@link put},
+ *   {@link patch}, `delete`, {@link head}, or {@link options}.
+ * - Add params, query, headers, payload, success, and error schemas in the
+ *   constructor options.
+ * - Attach endpoint-specific middleware or annotations with the methods on
+ *   {@link HttpApiEndpoint}.
+ * - Use helper types such as {@link Handler}, {@link HandlerRaw},
+ *   {@link ServerServices}, and {@link ClientServices} when integrating with
+ *   builders or clients.
+ *
+ * **Gotchas**
+ *
+ * - Paths use `HttpRouter.PathInput`; route parameters come from the router and
+ *   are decoded by the optional `params` schema.
+ * - With codecs enabled, params, query, and headers use string-tree codecs. Body
+ *   methods use JSON payload codecs by default; no-body methods use string-tree
+ *   payload codecs.
+ * - Multiple payload schemas can share a content type only when they use the
+ *   same encoding strategy. Multipart payloads cannot be combined under the same
+ *   content type.
+ * - Endpoint errors are merged with middleware errors for server encoding and
+ *   client decoding.
+ *
+ * **See also**
+ *
+ * - {@link PayloadMap} for the payload schema map stored on endpoints.
+ * - {@link Request} and {@link ClientRequest} for request helper types.
+ * - {@link Handler} and {@link HandlerRaw} for server handler signatures.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiError.ts

@@ -1,22 +1,42 @@
 /**
- * The `HttpApiError` module defines the built-in error types used by Effect's
- * unstable HTTP API layer for common failure responses.
- *
- * Each exported status error is a `Schema.ErrorClass` with an `httpApiStatus`
- * annotation, so it can be declared as an endpoint or middleware error schema
- * and then used by reflection, OpenAPI generation, clients, and server response
- * encoding. The classes also implement `HttpServerRespondable`, which means
- * using one directly as a server response produces an empty response with the
+ * Built-in error schemas for common HTTP API failure responses.
+ *
+ * This module provides reusable `Schema.ErrorClass` values for common HTTP
+ * status codes, plus `HttpApiSchemaError` for request decoding failures raised
+ * by the HTTP API runtime. The status errors are ready to use in endpoint or
+ * middleware error declarations and are understood by builders, generated
+ * clients, reflection, and OpenAPI generation.
+ *
+ * **Mental model**
+ *
+ * Each status error carries an `httpApiStatus` schema annotation and implements
+ * `HttpServerRespondable`. Declaring one as an endpoint error tells the server
+ * how to encode that failure and tells generated clients how to decode it. Using
+ * an instance directly as a server response produces an empty response with the
  * matching HTTP status.
  *
- * Use the `*NoContent` variants when the wire response intentionally has no
- * body but clients should still decode that status into a typed error value.
- * For custom error schemas, make sure to add the intended
- * `HttpApiSchema.status` annotation; error schemas without one are treated as
- * `500 Internal Server Error` by the HTTP API machinery. Schema failures raised
- * while decoding params, headers, query, body, or payload values are represented
- * separately by `HttpApiSchemaError`, which responds as `400 Bad Request` unless
- * transformed by middleware.
+ * **Common tasks**
+ *
+ * Use classes such as {@link BadRequest}, {@link Unauthorized}, {@link NotFound},
+ * or {@link InternalServerError} when an API error should have a typed body.
+ * Use the matching `*NoContent` exports when the wire response intentionally has
+ * no body but clients should still decode that status into a typed error value.
+ * Use {@link HttpApiSchemaError} to identify failures from decoding path
+ * params, headers, query values, body values, or payload values.
+ *
+ * **Gotchas**
+ *
+ * Custom error schemas need an explicit `HttpApiSchema.status` annotation when
+ * they should map to a status other than `500 Internal Server Error`. Request
+ * decoding failures are represented separately by {@link HttpApiSchemaError},
+ * which responds as `400 Bad Request` unless middleware transforms it into a
+ * declared API error.
+ *
+ * **See also**
+ *
+ * `HttpApiSchema` for status and no-content annotations, `HttpApiEndpoint` for
+ * declaring endpoint errors, `HttpApiMiddleware` for middleware error schemas,
+ * and `HttpApiBuilder` for server-side error encoding.
  *
  * @since 4.0.0
  */
@@ -407,7 +427,7 @@ export const ServiceUnavailableNoContent = ServiceUnavailable.pipe(HttpApiSchema
 /**
  * Type-level identifier used to mark `HttpApiSchemaError` values.
  *
- * @category Parsing errors
+ * @category type IDs
  * @since 4.0.0
  */
 export type HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSchemaError"
@@ -415,7 +435,7 @@ export type HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSche
 /**
  * Runtime identifier used to mark and detect `HttpApiSchemaError` values.
  *
- * @category Parsing errors
+ * @category type IDs
  * @since 4.0.0
  */
 export const HttpApiSchemaErrorTypeId: HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSchemaError"

package/src/unstable/httpapi/HttpApiGroup.ts

@@ -1,27 +1,38 @@
 /**
- * The `HttpApiGroup` module defines named collections of `HttpApiEndpoint`s
- * within an `HttpApi`.
- *
- * Groups are the main way to organize endpoints by a domain boundary, resource,
- * or feature area before those endpoints are added to an API and implemented
- * with `HttpApiBuilder.group`. A group carries its identifier, endpoint set,
- * annotations, and `topLevel` flag, which are later used by builders, clients,
- * URL builders, and OpenAPI generation. Non-top-level groups expose nested
- * client methods under the group name, while top-level groups expose their
- * endpoint methods directly.
- *
- * Composition is order-sensitive. Adding an endpoint with the same name as an
- * existing endpoint replaces it, and `prefix`, `middleware`,
- * `annotateEndpoints`, and `annotateEndpointsMerge` only affect endpoints that
- * are already present when those APIs are called. Group annotations apply to the
- * group itself; use the endpoint annotation helpers when metadata should be
- * attached to each endpoint.
- *
- * The type helpers in this module reflect the endpoint union for a group and
- * aggregate the services required by endpoint schemas, middleware, and declared
- * errors. Error schemas are still declared on endpoints, while middleware can
- * contribute additional error schemas and client/server service requirements
- * through the endpoint middleware set.
+ * Defines named collections of `HttpApiEndpoint`s inside an `HttpApi`.
+ *
+ * A group is the boundary for endpoints that belong to the same resource,
+ * feature area, or domain concern. Builders, generated clients, URL builders,
+ * and OpenAPI generation read the same group value, including its identifier,
+ * endpoint set, annotations, and `topLevel` flag.
+ *
+ * **Mental model**
+ *
+ * Start with {@link make}, add endpoints, then apply group-wide transforms such
+ * as `prefix`, `middleware`, or endpoint annotations. A regular group becomes a
+ * named namespace in generated clients. A `topLevel` group exposes its endpoint
+ * methods directly on the client.
+ *
+ * **Common tasks**
+ *
+ * Use this module to collect related endpoints, share a path prefix or
+ * middleware across the current endpoint set, attach metadata to the group or to
+ * each current endpoint, and derive group-level types for builders and generated
+ * clients.
+ *
+ * **Gotchas**
+ *
+ * Adding an endpoint with the same name as an existing endpoint replaces it.
+ * `prefix`, `middleware`, `annotateEndpoints`, and `annotateEndpointsMerge`
+ * affect only endpoints that are already present when those APIs are called.
+ * Group annotations stay on the group; use endpoint annotation helpers when
+ * metadata must be attached to each endpoint.
+ *
+ * **See also**
+ *
+ * `HttpApiEndpoint` for individual route contracts, `HttpApi` for composing
+ * groups into a complete API, and `HttpApiBuilder` for supplying
+ * implementations.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -1,28 +1,52 @@
 /**
- * The `HttpApiMiddleware` module defines middleware services that can wrap
- * `HttpApi` endpoint execution on the server and request execution in generated
- * clients.
- *
- * Use this module for cross-cutting HTTP API behavior such as authentication and
- * authorization, request logging or tracing, rate limiting, adding request-scoped
- * services to the endpoint context, normalizing schema errors, or installing
- * client-side request middleware for APIs that require the same concern on both
- * sides. Middleware services carry type-level metadata describing the services
- * they require and provide, the error schemas they may fail with, whether they
- * implement security schemes, and whether generated clients must provide a
- * matching client middleware.
- *
- * Security middleware is declared with non-empty `security` schemes and receives
- * decoded credentials from `HttpApiSecurity`; ordinary middleware receives only
- * endpoint and group metadata. Error declarations must be `Schema` values (or an
- * array of them) because middleware failures are added to the endpoint error
- * surface and must be encodable by the HTTP API builder. If a middleware turns
- * `HttpApiSchemaError` failures into API errors, use
- * `layerSchemaErrorTransform` and make sure the transformed error is covered by
- * the middleware's declared schema. Client middleware installed with
- * `layerClient` is made available through the `ForClient` marker and captures
- * its surrounding context, so client requirements should be declared explicitly
- * when `requiredForClient` is enabled.
+ * The `HttpApiMiddleware` module defines middleware service keys for
+ * declarative HTTP APIs. Middleware wraps endpoint execution on the server and,
+ * when required by an API, can also wrap requests made by generated clients.
+ *
+ * Middleware is where you put cross-cutting behavior that belongs to the API
+ * contract: authentication, authorization, request logging, tracing, rate
+ * limiting, request-scoped services, schema-error normalization, and client
+ * request decoration.
+ *
+ * **Mental model**
+ *
+ * - A middleware is declared with {@link Service}; the declaration is both a
+ *   `Context.Service` key and a typed description of the middleware contract.
+ * - Server implementations receive the endpoint response effect plus endpoint
+ *   and group metadata. Security middleware also receives decoded credentials
+ *   from the configured `HttpApiSecurity` scheme.
+ * - The service metadata records provided services, required services, declared
+ *   error schemas, client error types, security schemes, and whether generated
+ *   clients must install a matching client middleware.
+ * - Client middleware is published through the {@link ForClient} marker by
+ *   {@link layerClient} and participates in the generated client's request
+ *   pipeline.
+ *
+ * **Common tasks**
+ *
+ * - Declare middleware services with {@link Service}.
+ * - Detect security middleware with {@link isSecurity}.
+ * - Convert `HttpApiSchemaError` failures into declared API errors with
+ *   {@link layerSchemaErrorTransform}.
+ * - Install a generated-client middleware with {@link layerClient}.
+ *
+ * **Gotchas**
+ *
+ * - Middleware error declarations must be `Schema` values, or arrays of
+ *   `Schema` values, because builders and clients encode and decode them as
+ *   part of the endpoint error surface.
+ * - A security middleware must declare at least one security scheme. Ordinary
+ *   middleware does not receive credentials.
+ * - A schema-error transform must fail with an error covered by the middleware's
+ *   declared error schema.
+ * - `requiredForClient` adds a client-side requirement. Provide it with
+ *   {@link layerClient}; the layer captures its surrounding context.
+ *
+ * **See also**
+ *
+ * - {@link Service} for declaring middleware service keys.
+ * - {@link layerSchemaErrorTransform} for mapping schema failures.
+ * - {@link layerClient} for generated-client middleware.
  *
  * @since 4.0.0
  */
@@ -324,7 +348,7 @@ export type ServiceClass<
  *
  * **When to use**
  *
- * Use the optional configuration to declare required services, provided services,
+ * Use when you use the optional configuration to declare required services, provided services,
  * typed error schemas, security schemes, client errors, and whether generated
  * clients must provide a matching client middleware.
  *

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -1,22 +1,34 @@
 /**
- * The `HttpApiScalar` module mounts an interactive Scalar API reference for a
- * declarative `HttpApi`.
+ * Scalar documentation UI for declarative `HttpApi` contracts.
  *
- * Use this module when you want a browser-friendly documentation page for an
- * `HttpApi` without maintaining a separate OpenAPI document. The `layer`
- * helper registers a `GET` route on an `HttpRouter`, generates the OpenAPI
- * specification with `OpenApi.fromApi`, embeds it into the HTML page, and loads
- * the bundled Scalar browser script. `layerCdn` provides the same UI while
- * loading Scalar from jsDelivr, optionally pinned with `version`.
+ * Use this module to mount a browser-based API reference on an `HttpRouter`
+ * without writing or storing a separate OpenAPI file. The route renders an HTML
+ * page containing the OpenAPI document produced from the supplied `HttpApi` and
+ * boots Scalar in the browser.
  *
- * The mounted path is a documentation UI route, defaulting to `/docs`, rather
- * than a raw JSON specification endpoint. If clients, gateways, or external
- * documentation pipelines need the OpenAPI document directly, expose it
- * separately with `HttpApiBuilder.layer`'s `openapiPath` option. Scalar
- * configuration is forwarded to the page through `ScalarConfig`; values such as
- * `proxyUrl`, theme and layout settings, and `baseServerURL` matter when
- * enabling "Test Request", styling the docs, or rendering relative server URLs
- * outside the browser origin.
+ * ## Mental model
+ *
+ * {@link layer} serves the UI with the bundled Scalar script. {@link layerCdn}
+ * serves the same UI while loading Scalar from jsDelivr, optionally pinned with
+ * `version`. Both helpers register a `GET` route, defaulting to `/docs`, and
+ * pass {@link ScalarConfig} through to Scalar's HTML configuration.
+ *
+ * ## Common tasks
+ *
+ * - Use {@link layer} when the application should serve the bundled Scalar
+ *   assets without depending on a CDN at runtime.
+ * - Use {@link layerCdn} when a CDN-loaded Scalar bundle is preferred, and pin
+ *   `version` when repeatable output matters.
+ * - Set `path` to mount the documentation UI somewhere other than `/docs`.
+ * - Set `proxyUrl`, theme, layout, and `baseServerURL` in `ScalarConfig` for
+ *   request testing, styling, and relative server URLs.
+ *
+ * ## Gotchas
+ *
+ * The mounted route is an HTML documentation page, not a raw OpenAPI JSON
+ * endpoint. If clients, gateways, or documentation pipelines need the OpenAPI
+ * document directly, expose it separately with `HttpApiBuilder.layer`'s
+ * `openapiPath` option.
  *
  * @since 4.0.0
  */
@@ -53,7 +65,10 @@ export type ScalarThemeId =
 /**
  * Configuration passed to the embedded Scalar API reference UI.
  *
- * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+ * **Details**
+ *
+ * This configuration follows Scalar's API reference configuration:
+ * https://github.com/scalar/scalar/blob/main/documentation/configuration.md
  *
  * @category models
  * @since 4.0.0