Changelog

(feat): Support generating from a composed workspace. A workspace that declares no specs of its own and composes sibling workspaces through dependencies.yml now exposes those dependencies’ specs, namespaced by the directory of the package marker that exports them, so it can produce a source archive instead of failing with “workspace type fern does not expose source specs”.

(fix): fern export now emits anyOf (instead of oneOf) for undiscriminated unions. Undiscriminated union members can overlap (e.g. a set of string literals alongside string), so oneOf caused strict JSON Schema validators to reject values that matched more than one member.

(fix): Allow replay to be enabled for SDK generators routed through sdk-gen-api. Previously, generators with both sdkGenApiRoute and replay.enabled: true failed with a configuration error.

(fix): fern generate --docs now fails when a rule configured as error in docs.yml check.rules (e.g. broken-links: error) reports a violation, matching the behavior of fern check. Previously the violation was logged but docs were still published.

(fix): Propagate AsyncAPI message description/summary to WebSocket channel message docs so they appear in the API reference and generated SDK docstrings. Previously only the payload schema’s description survived import.

(feat): The OpenAPI importer now honors x-twilio.libraryVisibility (public | private | hidden) during SDK generation. Visibility is read from the operation, path item, or info object (most specific wins), and from parameters, schemas, and object properties. fern generate keeps only public elements; the new fern generate --private flag also keeps private elements. hidden elements are never generated. Other commands (fern check, fern generate-ir) are unaffected.

(chore): Add a pre-prod CLI build target that uses Postman-hosted production sdk-gen service origins (sdk-gen.postman.co and related service domains) ahead of DNS cutover.

(feat): Add theme.site-switcher to docs.yml and global themes. When enabled, docs sites published to the same domain under different basepaths are listed in a header site switcher; order, hide, labels, and show-products control presentation.

(fix): Preserve API import settings that affect documentation when fern sdk migrate decouples docs.yml from generators.yml.

(fix): An explicitly empty array in an OpenAPI overrides file (e.g. security: [] to opt an endpoint out of global auth) now replaces the original array instead of being ignored.

(feat): Add api.settings.webhook-signature to generators.yml. Declares an API-wide webhook signature scheme (same shape as a webhook signature block) once, outside the API definition, and compiles it into sdkConfig.webhookSignatureVerification in the IR so every SDK generator emits the shared webhook verification helper without any webhooks or x-fern-* extensions in the spec.

(feat): Support secure SDK Config v1 direct publishing to npm, Maven, PyPI, and crates.io through sdk-gen-api.

(fix): Hosted MCP deploys now fail fast, before uploading anything, when a generated tool name is longer than 64 characters or contains disallowed characters, and suggest an x-fern-mcp-name overlay for the operation (method + path). Deploy errors from the registry now include each validation issue instead of only the headline message.

(feat): Add fern docs theme download --name <name> [--org <org>] [--output <dir>], which fetches an org-level theme from Fern’s cloud and writes it as a local theme directory (theme.yml plus its logo/font/css/js assets with relative paths). The inverse of fern docs theme upload; useful for vendoring a theme into a self-hosted docs image so global-theme resolves without network access.

(fix): Docs validation no longer logs a “Slow file read” debug line for every markdown page when many files are read concurrently (the timing included threadpool queue time, not disk speed). It now logs one summary per validation run and only flags reads that are outliers relative to the batch.

(fix): The CLI now defaults UV_THREADPOOL_SIZE to 8 (from Node’s default of 4) so concurrent file reads spend less time queued behind the libuv threadpool. Set the variable explicitly to override.

(fix): Fix environments defined in generators.yml disappearing from docs (GET ///path, empty Try It base URL) when an api: navigation block uses audiences:. Environments that don’t declare audiences are now retained under audience filtering, matching the Fern Definition behavior.

(fix): The OpenAPI error-responses setting now replaces a pre-existing components.schemas entry of the same name when nothing references it anymore once the 4xx/5xx responses have been rewritten (the common case: a legacy error body under apply-to: all), so specs that ship their own TwilioServiceErrorResponse-style schema no longer need a per-spec overlay to remove it first. If the legacy schema is still referenced (a 2xx body, another schema, apply-to: untyped), the error now lists the offending JSON Pointers.

(fix): Fix OpenAPI allOf required-ness when a branch lists a property in required that is defined only by another (parent) branch. The property is now required on the composed type, so a nullable: true property becomes required-nullable and round-trips null in generated SDKs. Multi-level allOf chains are handled; properties required in no branch stay optional.

(internal): The CLI now sends an X-Fern-Agent header on every FDR, Venus and Fiddle request (and tags its own telemetry events with agent) when run from a coding agent (Claude Code, Cursor, Codex, Devin, Gemini CLI), so agent-driven usage such as docs publishes can be measured separately from human usage.

(fix): fern init --docs now produces a project that builds with no further edits. When no API definition exists in the fern folder, it scaffolds pages/welcome.mdx and points the navigation at it instead of emitting an api: item with nothing to render. fern check also reports a new api-section-has-definition error when an api: navigation item does not resolve to any API definition, instead of passing and then failing at build time.

(feat): Add an error-responses OpenAPI setting that applies a single error body schema (e.g. RFC 9457 Problem Details) to the 4xx/5xx responses of every operation in a spec, so per-spec overlays are no longer needed to type error responses.

api:
  specs:
    - openapi: openapi.yml
      settings:
        error-responses:
          schema: errors/problem_details.yml   # file path or inline schema