# Changelog

Source: https://apigenie.pl/changelog

What changed in each release of the CLI. The newest release is on the [downloads](/downloads) page.

## 0.12.0 (2026-11-08)

`apigenie lint` loads Spectral ruleset files and gains the `camara` and `owasp` rulesets, and the commands of
`apigenie`, `apigenie-generator` and `apigenie-catalog` take `--json`. The generators add Avro payloads for AsyncAPI
and experimental Rust and Swift targets; `apigenie-mcp` (experimental) and the desktop editor's installers ship with
the CLI.

### Added

- **Spectral ruleset files in `apigenie lint`** (ADR-217): `extends` in the OpenAPI, AsyncAPI and Swagger
  sections takes the path of a ruleset file (`extends: [recommended, ./lint/team.spectral.yaml]`), and
  `--ruleset FILE` adds one from the command line. A file's own `extends`, `functions` and `functionsDir`
  resolve against it. `[ruleset, recommended|all|off]` pairs in `extends`, and `recommended: false` in ruleset
  files, work as in Spectral, and the configuration can re-tune or turn on the rules a file defines. Files are local: URLs are
  refused. In a ruleset file, `spectral:oas`, npm packages other than `@stoplight/spectral-owasp-ruleset` and
  settings of rules API Genie doesn't have are skipped with a warning, so the 41 rules of CAMARA's
  `.spectral-r4.yaml` and its functions load unchanged.
- **The `camara` ruleset in `apigenie lint`**: `extends: [camara]` lints OpenAPI documents with the CAMARA
  project's `.spectral-r4.yaml` and its 14 JavaScript functions, which ship with API Genie. A CAMARA repository
  needs no copy of the file. Its 41 rules keep CAMARA's ids, 2 of them `recommended: false`, and `rules`
  re-tunes them. It extends the `owasp` ruleset, as the file does upstream, with CAMARA's settings of its rules;
  `spectral:oas`, which it also extends, is skipped without a warning. The file's `operation-success-response:
  true` turns on API Genie's rule of that id.
- **`bundle: true` in the lint configuration**: `commands.lint.bundle` bundles the local files an OpenAPI 3.x
  document references into it before linting, on every run, as `--bundle` does. A CAMARA repository, whose APIs
  reference `../common/CAMARA_common.yaml`, lints with no flags once its configuration sets `extends: [camara]`
  and `bundle: true`. `--fix` ignores it and fixes each file as it is.
- **The `owasp` ruleset in `apigenie lint`**: `extends: [owasp]` lints OpenAPI and Swagger 2.0 documents against
  the OWASP API Security Top 10 (2023) with Spectral's `@stoplight/spectral-owasp-ruleset` 2.0.1, its 32 rules
  and 2 JavaScript functions, which ship with API Genie. A ruleset file that extends
  `@stoplight/spectral-owasp-ruleset` gets it too, instead of a warning. On the upstream ruleset's 121 test
  documents it reports what Spectral reports, except on one that API Genie doesn't read (an `apiKey` scheme
  `in: path`). The upstream tests have no case for `owasp:api2:2023-read-restricted` and
  `owasp:api2:2023-write-restricted`. Like Spectral, they report each operation that no security scheme protects.
  As in Spectral, none of its rules lints AsyncAPI documents.
- **`constructor.name` in JSONPath filters**: `@.type.constructor.name === 'Array'` tells an array from an object,
  as OpenAPI 3.1 rulesets do for `type: [string, "null"]`.
- **JSONPath `^`, `console` and `documentInventory.graph`** (ADR-217): the jsonpath-plus parent operator `^`
  in `given` and `field`; `console.log`, `info`, `warn`, `error` and `debug` in JavaScript functions, whose
  output is dropped; and `context.documentInventory.graph.overallOrder()`, each distinct `$ref` value of the
  document. A `message` in a rule's `then`, which Spectral rulesets carry, is accepted and ignored.
- **`apigenie-generator ... --check`** (ADR-227) on every `client`, `server` and `schema` target: the generator runs
  as usual but writes nothing, compares the files it would write with the output directory, prints the ones that
  would be created or changed, and exits with 1 when there are any, as `apigenie format --check` does. Files a
  target writes only when they are missing (controllers, implementation packages, tests) are compared only until
  they exist, and files the generator doesn't write are not compared. CI can check that the generated code in a
  repository matches the API description in one step: the guide "Generate a client and a server" shows it.
- **`apigenie-generator client rust` and `apigenie-generator server axum` generate Rust crates (experimental)**:
  the client, on reqwest, has an async method per operation returning an enum of the documented responses. It has
  credentials per security scheme, typed server-sent event and JSON Lines streams, and multipart and form bodies.
  The server, on axum, has an `Api` trait to implement and a router whose handlers check security and validate
  parameters and bodies before calling it, answering invalid requests with problem details. Both share serde models
  that validate their constraints, need Rust 1.85, and pass `cargo fmt --check` and `cargo clippy -D warnings` as
  generated. The server doesn't send callbacks or webhooks yet, and AsyncAPI documents are refused.
- **`apigenie-generator client swift` (experimental) generates Swift clients**: a SwiftPM package (Swift 6, iOS 16,
  macOS 13, tvOS 16, watchOS 9 and Linux) without dependencies, whose `Client` has an async method per operation
  returning an enum with a case per documented status (`.created(body: Shipment, headers: ...)`,
  `.notFound(Problem)`); an undocumented status throws `ClientError.undocumentedStatus`. Models are `Codable`,
  `Sendable` and `Hashable` structs and enums that tell missing properties from null ones (`Nullable<T>?`), decode
  `oneOf` by discriminator with `defaultMapping`, keep enum values the document doesn't list (`unknown(String)`), and
  check the constraints of their schemas with `validate()`, request bodies before they are sent. Requests go through
  an `HTTPTransport` protocol, URLSession by default; server-sent events, JSON Lines and JSON text sequences are
  `AsyncThrowingStream`s of their `itemSchema`, multipart bodies are structs of `MultipartFile`s and values,
  parameters are written in the `simple`, `label`, `matrix`, `form`, `spaceDelimited`, `pipeDelimited` and
  `deepObject` styles, operation and path servers are honoured, and `Credentials` holds a value per security scheme
  (API keys, HTTP basic and bearer, an OAuth 2 or OpenID Connect token provider, mutual TLS). Configured under
  `commands.generate.client_swift`.
- **`apigenie-generator server vapor` and `server hummingbird` (experimental) generate Swift servers**: a SwiftPM
  package on Vapor 4 or Hummingbird 2 whose code is the same except the adapter registering the routes and
  `Package.swift`. An `APIHandler` protocol has an async method per operation taking its request (parameters, body,
  credentials) and returning the response enum of the Swift client; the routes check security requirements and decode
  and validate parameters and bodies (JSON, forms, multipart, JSON Lines, text, bytes) before the handler runs,
  answering 400 with RFC 9457 problem details that list JSON pointers, and stream server-sent events and JSON Lines as
  the items come. `WebhookSender` and `CallbackSender` send the document's webhooks and callbacks. Configured under
  `commands.generate.server_vapor` and `commands.generate.server_hummingbird`.
- **`apigenie-generator client kafkajs` and `server kafkajs` generate Avro payloads, security, conditions and base64
  strings**: Avro records and enums become TypeScript types, encoded in Avro's binary encoding by a dependency-free
  codec, with the schema id from `KafkaOptions.schemaRegistry` (a Confluent-compatible registry, or a function) in the
  payload or in a header, as the message's Kafka binding says. `kafka.ts` lists the SASL (SCRAM, PLAIN) and X.509
  schemes of each server, and `securityConfig(server)` builds KafkaJS's `ssl` and `sasl` options from the environment
  variables of their credentials. The payload validators check `if`/`then`/`else`, `dependentRequired`,
  `dependentSchemas` and draft-07 `dependencies`, also in `server express`, and `contentEncoding: base64` strings are
  `Uint8Array`s.
- **`apigenie-generator server spring` and `client java` generate Avro payloads**: a message with an Avro schema
  carries the class that `avro-maven-plugin` generates from its schema (`src/main/avro/<full name>.avsc`), encoded by
  `KafkaAvro` in Avro's binary encoding with the schema id from a registry (a `KafkaAvro.SchemaRegistry` bean or
  option, or the Confluent-compatible registry of the server's `schema-registry-url`) in the payload or in a header,
  as the message's Kafka binding says.
- **`apigenie-generator server aspnet` and `client csharp` generate Avro payloads and security**: a message with an
  Avro schema carries an `ISpecificRecord` class of its record (`Avro/<full name>.cs`), encoded by `KafkaAvro` with
  Apache.Avro and the schema id from a registry (an `ISchemaRegistry` service or option, or the Confluent-compatible
  registry at `SchemaRegistryUrl`) in the payload or in a header. The `Security` setting names the SASL (SCRAM, PLAIN)
  or client certificate scheme the consumers and producers connect with, its credentials read from environment
  variables named after the scheme.
- **`apigenie-generator server go` and `client go` generate Avro payloads and security for AsyncAPI documents**: a
  message with an Avro schema carries a struct of its record (`avro.gen.go`), written and read in Avro's binary encoding
  by the generated codec, with the schema id from `Options.SchemaRegistry` or the Confluent-compatible registry of the
  server binding's `schemaRegistryUrl` in the payload or in a header. `security.gen.go` has a function per SASL (SCRAM,
  PLAIN) or client certificate scheme returning its franz-go options, and `SecurityFromEnvironment` reads their
  credentials from environment variables named after the scheme (`main.go -security kafkaScram`). The models map
  `contentEncoding: base64` strings to `[]byte`, also in the OpenAPI `server go` and `client go`.
- **The C#, Java, Python and Go models check `not` and draft-07 `dependencies`**: `server aspnet`, `client csharp`,
  `server spring`, `client java`, `server fastapi`, `client python`, the Python Kafka packages and the Go Kafka packages
  reject values that match a `not` schema on the presence and constant values of properties (in `if`/`then`/`else` too)
  and check `dependencies` as `dependentRequired` and `dependentSchemas`; C# conditions on properties with defaults tell
  set properties from defaulted ones, and closed tuples get their length as `MaxLength`.
- **`apigenie-generator server spring` and `client java` configure the Kafka servers' security**: each SASL (SCRAM,
  PLAIN) or client certificate scheme gets a Spring profile in `application.yaml` (`--spring.profiles.active=kafka-scram`)
  and a `<scheme>Security(...)` method in the Java client's options, with `securityFromEnvironment()` reading the
  credentials from environment variables named after the scheme (`KAFKA_SCRAM_USERNAME`, `KAFKA_MTLS_CERT`, ...).
- **`apigenie-generator client ws` and `server ws` generate security and the WebSocket binding's headers**: a
  channel takes the security schemes of its operations, or of its servers. Clients send the `credentials` of a
  scheme as its API key query parameter, header or cookie, as basic credentials, or as a bearer token in the
  `Authorization` header or the `access_token` query parameter; servers check them with the authenticators of
  `authenticate`, refuse a handshake without valid credentials with status 401 and one without a required binding
  header with 400, and give sessions `principal` and the typed `bindingHeaders`. Schemes that a handshake can't
  carry are reported. Types of `anyOf` alternatives with only `required` keep the object's properties, and
  `patternProperties` are typed as records.
- **`apigenie-generator server phoenix` and `client elixir` generate Avro payloads, security, client ids and the
  WebSocket binding's headers for AsyncAPI documents**: a message with an Avro schema carries a struct of its record
  (`lib/<app>/avro/`), written and read in Avro's binary encoding by a dependency-free codec, with the schema id from a
  Confluent-compatible registry (the Kafka supervisor's `:schema_registry`, or `KAFKA_SCHEMA_REGISTRY_URL` in `server
  phoenix`) in the payload or in a header. `<Root>.Kafka.Security` has brod's configuration of each SASL (SCRAM, PLAIN)
  or client certificate scheme, with the credentials of environment variables named after the scheme
  (`KAFKA_SECURITY=kafkaScram`), and the brod clients take the client ids of the Kafka bindings. The Phoenix channels
  check the credentials of their security schemes with the `authenticate/2` callback of `<Root>Web.Security` and decode
  the binding's headers; the client's `connect` sends `:credentials` and `:headers` with the handshake. The models check
  `not`.
- **`apigenie-generator client python` generates Avro payloads and security for AsyncAPI documents**: a message with an
  Avro schema carries a Pydantic model of its record (`avro.py`), written and read with fastavro, with the schema id
  from the `schema_registry` option (by default the Confluent-compatible registry of the server) in the payload or in a
  header. `security.py` has the aiokafka settings of each SASL (SCRAM, PLAIN) or client certificate scheme, and the
  `security` option names the one the client connects with, its credentials read from environment variables named after
  the scheme.
- **`apigenie-generator server faststream` generates security, Avro payloads and the AMQP and MQTT message bindings**:
  `security.py` gives each broker the FastStream security object of the scheme its `<SERVER>_SECURITY` variable names
  (SASL, client certificates, MQTT tokens), with the credentials of environment variables. Kafka subscribers read
  Avro payloads with fastavro. AMQP messages are sent with their content type, `gzip` or `deflate` content encoding
  and message type, MQTT requests with their response topic and correlation data, and Kafka records with their key.
  Channel parameters with enums are `Literal`s, and those located in the payload are read from it. The models reject
  what their schemas don't allow and carry the payload examples for the AsyncAPI page.
- **`apigenie-generator server elixir-grpc` and `client elixir` check the required fields of requests**: a generated
  `<Root>.Validation` module checks the fields marked `(google.api.field_behavior) = REQUIRED`, in the request and in
  the messages it holds. The server answers a request without a required field with INVALID_ARGUMENT, and doesn't
  call the implementation. The client doesn't send such a request: the call returns the same error, and a streamed
  call is cancelled. The messages in a partial update (a message with a `google.protobuf.FieldMask`) aren't checked.
- **`apigenie-generator server absinthe` serves subscriptions**: when the schema has a subscription type, the
  application serves subscriptions over a WebSocket at the GraphQL endpoint with the graphql-transport-ws protocol,
  and `<Root>.PubSub.publish/2` publishes the values of a subscription field. The pubsub serves one node, and every
  subscription of a field gets every value published to it, whatever its arguments. The generator no longer warns that
  subscriptions have no transport.
- **The client and server generators of `apigenie-generator` read Swagger 2.0 documents**: they convert a Swagger
  2.0 document in memory to OpenAPI 3.2, with its polymorphism (a `discriminator` and the definitions extending it
  with `allOf`) as a union whose mapping comes from `x-discriminator-value`. What the conversion approximates is
  reported as a warning at its position in the Swagger document, as are the generators' own warnings; a reference to
  another document is an error. `--overlay` overlays apply to the Swagger document. The Java and Spring generators
  also read the `x-pattern-message`, `x-size-message`, `x-minimum-message` and `x-maximum-message` of a parameter
  from the parameter itself, where Swagger 2.0 documents have them.
- **`apigenie-generator client python` sends content parameters, several media types, streams and client
  certificates**: a parameter described with `content` is sent whole, as JSON for JSON media types. A body with
  several media types takes a `content_type` argument, and JSON Lines and `application/json-seq` bodies are iterables
  of their `itemSchema`. A response that can be JSON or a stream gets a `<method>_stream` method returning a `Stream`
  of its server-sent events, JSON Lines or JSON text sequence items. Models check `if`/`then`/`else`,
  `dependentRequired` and `dependentSchemas` when they only test the presence and the values of properties, and
  `mutualTLS` schemes take a client certificate.
- **`apigenie-generator server fastapi` decodes styled parameters, streams bodies and documents callbacks and
  webhooks**: `pipeDelimited`, `spaceDelimited`, non-exploded `form` and header arrays are split into their items,
  and `deepObject` and JSON `content` parameters are validated into their models. Server-sent events, JSON Lines and
  JSON text sequences are streamed when they are the only content of the response, or when the `Accept` header names
  them first, and streamed request bodies reach the implementation as async iterators. Callbacks, webhooks and
  response links are described in the served OpenAPI document, and `x-internal` operations are left out of it.
- **`apigenie-generator server fastapi` models tuples, conditions and `readOnly`/`writeOnly`, and passes the client
  certificate of mutual TLS to `BaseSecurity`**: `prefixItems` are `tuple[...]` when the array has exactly one item
  per position, lists of the union of the positions otherwise. Conditions are checked by a `model_validator` when
  they only test the presence and the values of properties, `unevaluatedProperties: false` rejects unknown
  properties, and models with `readOnly` or `writeOnly` properties get an input variant for request bodies.
  `validate_<scheme>` of `BaseSecurity` receives the client certificate of the request, e.g. `validate_mutual_tls`
  for a scheme named `mutualTLS`.
- **`apigenie-generator client elixir` and `server phoenix` models check constraints, tuples, `patternProperties` and
  conditions**: `new/1` checks the string, number, array and object constraints of the schemas. `prefixItems` are
  tuples when the array is closed, every position is required and the positions are simple types, otherwise lists
  checked position by position. `patternProperties` are the entries of a map checked against the schema of their
  pattern. `if`/`then`/`else`, `dependentRequired` and `dependentSchemas` are checked when they only test the
  presence and the values of properties. `readOnly` properties are left out of the requests a client sends and
  `writeOnly` properties out of the responses a server sends.
- **`apigenie-generator client elixir` and `server phoenix` stream events and JSON Lines**: `text/event-stream`,
  JSON Lines and `application/json-seq` bodies are enumerables of their items, typed by the `itemSchema`. The client
  decodes a streamed response lazily as it arrives, and the server sends each item as a chunk. When a status of a
  Phoenix operation has several media types, the server sends the first one, in the document's order, that the
  `Accept` header accepts.
- **`apigenie-generator server phoenix` sends webhooks and callbacks and serves mutual TLS**: `<App>.Senders` has a
  function per webhook and per request of a callback, sending it with Req. With a `mutualTLS` security scheme,
  `config/runtime.exs` also serves the API over https and verifies client certificates when `TLS_CERTFILE`,
  `TLS_KEYFILE` and `TLS_CACERTFILE` are set.
- **`apigenie-generator client go` and `server go` model tuples, `patternProperties` and conditions**: a `prefixItems`
  tuple whose positions are references or scalars of one type is a slice of that type, and `Validate()` checks each
  position and the length of closed tuples. An object whose keys match one pattern is a map of the pattern's type, and
  `Validate()` checks the keys and values of each pattern. `Validate()` checks `dependentRequired`, and
  `if`/`then`/`else` and `dependentSchemas` when their schemas use only `required` and the `const` and `enum` of
  properties. The Go Kafka generators type tuples the same way and check `if`/`then`/`else` within the same
  limits.
- **`apigenie-generator server go` streams events and sends webhooks and callbacks**: `text/event-stream` responses
  take a channel of `ServerSentEvent[T]`, and JSON Lines responses with an `itemSchema` a channel of their items, each
  written and flushed as it arrives. `WebhookSender` and one sender per callback send the requests the API makes, with
  their parameters serialized like the client's.
- **`apigenie-generator client csharp` and `server aspnet` model tuples, `patternProperties`, `multipleOf` and
  conditions**: a `prefixItems` tuple is a list of the type its items share, with a maximum length when it is closed.
  An object whose keys match one pattern is a `Dictionary`; with several patterns it is a record whose `Entries` hold
  the values. A generated `[MultipleOf]` attribute checks `multipleOf`, and records with `if`/`then`/`else` conditions
  or key patterns implement `IValidatableObject`. The asyncapi C# generators share the models.
- **`apigenie-generator client csharp` runs OAuth 2.0 flows**: an `OAuthClient` gets tokens with client credentials,
  the authorization code flow with PKCE and the device authorization flow. It renews them before they expire, with the
  refresh token when there is one.
- **`apigenie-generator server aspnet` checks OAuth 2.0 scopes**: when each alternative of an operation's security
  requirements lists OAuth 2.0 or OpenID Connect scopes, the endpoint answers 403 unless the user has those of one
  alternative.
- **`apigenie-generator server aspnet` reads object and `content` parameters**: `deepObject`, exploded form and
  delimited objects, and parameters described by JSON `content`. It also reads form fields with the `deepObject`
  encoding, and file arrays whose items have a `contentMediaType`.
- **`apigenie-generator server aspnet` answers in every media type of a response**: files, text, `text/event-stream`
  (`ServerSentEventsHttpResult<T>`) and JSON Lines (`JsonLinesHttpResult<T>`), with streams typed by the item schema.
- **`apigenie-generator server aspnet` sends webhooks and callbacks**: `Senders/` has typed HTTP clients, a
  `WebhookSender` and a class per callback of an operation, registered in a new `Program.cs`.
- **`apigenie-generator client java` requests OAuth 2 tokens**: with the `RestClient` and `RestTemplate` libraries, an
  OAuth 2 scheme gets an `OAuth` authentication. It requests tokens with client credentials, renews them and uses
  refresh tokens, each flow at its own token URL. It runs the authorization code flow (with PKCE) and the device
  authorization flow (OpenAPI 3.2) step by step. `ApiClient` gets `setOAuthClientCredentials`.
- **`apigenie-generator client java` presents client certificates**: with the `RestClient` and `RestTemplate`
  libraries and a `mutualTLS` scheme, `ApiClient` gets `withClientCertificate` (a key store and a trust store),
  `loadKeyStore` and `sslContext`.
- **`apigenie-generator server spring` covers callbacks, webhooks, `deepObject` and streaming**: with
  `annotationLibrary: swagger2`, operations that register callbacks get `@Callback` annotations, and an
  `ApiWebhooks` interface documents the webhooks with `@Webhooks`. `deepObject` query parameters of objects and maps
  are read by a generated argument resolver (`@DeepObjectParameter`), which answers 400 when a value doesn't convert
  or two keys conflict. In Spring MVC (WebFlux already did), streaming responses (`text/event-stream`, JSON Lines,
  JSON sequences) of arrays return a `Flux` of their items. The SpringDoc configuration describes the flows of OAuth 2
  schemes and `mutualTLS` schemes, and `writeOnly` properties get `Schema.AccessMode.WRITE_ONLY`.
- **`apigenie-generator client java` and `server spring` model tuples, `patternProperties`, `multipleOf` and
  conditions**: a `prefixItems` tuple is a list of the type its items share, with a maximum size when `items: false`
  closes it. An object without properties whose keys match one pattern is a `Map`; with several patterns, or with
  `additionalProperties: false`, it is a class that reads each value as the type of its key's pattern. With
  `additionalProperties: false`, a key that matches no pattern fails to deserialize. With `useBeanValidation`, a
  generated `MultipleOf` constraint checks `multipleOf`. With it, `@AssertTrue` methods check the `if`/`then`/`else`,
  `dependentRequired` and `dependentSchemas` conditions on which properties are present and their constant values.
- **`apigenie-generator client fetch` sends alternative request media types and JSON `content` parameters**: an
  operation with request media types of one kind (`application/merge-patch+json` and `application/json-patch+json`)
  gets a `contentType` param. A parameter described by JSON `content` is sent as JSON text; the client of `server mcp`
  does the same. The tools of `server mcp` take a body with several media types of one kind in any of them, with a
  `contentType` argument naming the one sent, and check the body against the schema of that media type.
- **`apigenie-generator server mcp` reads a discriminator's `defaultMapping`** (`x-defaultMapping` before 3.2): a value
  without the discriminating property, or with a value of it that the mapping doesn't name, is validated against the default
  option, as `server orpc` does.
- **`apigenie-generator server mcp` supports mutual TLS**: with a `mutualTLS` scheme, the server presents the client
  certificate that `<PREFIX>_<SCHEME>_CERT` and `<PREFIX>_<SCHEME>_KEY` name (PEM files), and checks the API's certificate against
  the CA bundle of `<PREFIX>_<SCHEME>_CA`, set with them or alone. Only the first `mutualTLS` scheme gets them. A package generated for such a document
  depends on `undici` 7.
- **Five AsyncAPI lint rules**, the core rules of the AsyncAPI parser (`asyncapi validate`) that the linter lacked:
  `operation-messages-from-channel` reports a message of an operation, or of its reply, that is not a reference to a
  message of its channel; `operation-channel-in-channels` an operation of the root `operations` whose channel is not
  under the root `channels`; `channel-servers-in-servers` a server of a root channel that is not under the root
  `servers`; `channel-address-no-query` a channel address with a query or a fragment. These four are an `error` in
  `recommended`, `strict` and `all`. The first three report a reference to another file, which
  `asyncapi validate` accepts.
  `latest-version` suggests AsyncAPI 3.1.0 to an older document, as a `hint` in `strict` and `all`.
- **Three OpenAPI lint rules**, a `warning` in `recommended` and an `error` in `strict` and `all`:
  `operation-tags-declared` reports a tag an operation uses that the document's `tags` does not declare, and `--fix`
  declares it; `server-urls-no-trailing-slash` reports a URL in the top-level `servers` that ends with a slash, and
  `--fix` removes it; `ref-no-siblings` reports, in OpenAPI 3.0, a key next to `$ref`, other than an extension, that
  the specification says to ignore. They are the counterparts of Spectral's `operation-tag-defined`,
  `oas3-server-trailing-slash` and `no-$ref-siblings`, and Redocly's `operation-tag-defined`,
  `no-server-trailing-slash` and `spec-ref-siblings`. When `server-urls` and `server-urls-no-trailing-slash` both
  fix one URL, one `--fix` makes one of the two changes and the next run the other.
- **`apigenie-catalog versions` and `apigenie-catalog release`** (ADR-206): a release of a specification is a Git
  tag named by `catalog.tags.pattern` (`{name}-{version}` by default, so `orders-api-1.4.0`). `release NAME VERSION`
  creates the annotated tag at HEAD. It refuses when the version is not a semantic version above the latest release,
  the tag is taken, the file has changes that are not committed or its `info.version` is not the version;
  `--dry-run` only checks, `--push` pushes the tag. `versions NAME` lists the releases, newest first, and says when
  the file's `info.version` is not released. The catalog section gains `tags.pattern` and, per specification,
  `lifecycle` (`draft`, `active`, `deprecated`, `retired`; a retired specification can't be released) and `sunset`,
  which `list` shows in a LIFECYCLE column. Both commands have `--json` (`apigenie-catalog-versions-report.json`,
  `apigenie-catalog-release-report.json`).
- **`--json` on every command** (ADR-198) of `apigenie`, `apigenie-generator`, `apigenie-catalog` and the
  `apigenie-server session` commands: the standard output holds one JSON document and nothing else. Commands with
  a report print it (`lint`, `diff` and `changelog` as with `--formatter json`, `test` its test report, `evolve
  plan`, `i18n check`, `config`, `config schema`, `apigenie-catalog list`), `format` prints each file and whether it
  changed (`apigenie-format-report.json`), and the other commands print the status of the run: the exit status,
  the error and warning messages and what they would have printed (`apigenie-status-report.json`), also when the
  command line can't be parsed. Exit statuses don't change, and messages still go to the standard error.
- **Instructions for coding agents** (ADR-203): `distribution/agents/AGENTS.md` is a section to paste into the
  `AGENTS.md` (or `.github/copilot-instructions.md`, `.cursor/rules`, ...) of a repository, telling an agent to lint,
  format and diff the API descriptions it changes with `--json`, and the guide "Work with AI agents" shows it. The
  `api-genie` skill of the Claude Code plugin, which agents that load Agent Skills can use on its own, uses `--json`.
- **`apigenie init`** (ADR-201) sets a repository up: it writes `apigenie.yaml` with the lint rules (`--ruleset`)
  of the families of API descriptions it finds, and the section of `distribution/agents/AGENTS.md` into
  `AGENTS.md` (or `--agents-file`), appending it to a file without it. Files that are there are kept, so a second
  run changes nothing; `--dry-run` writes nothing, and `--json` prints `apigenie-init-report.json`.
- **Markdown copies of the documentation sites of `apigenie-generator docs`** (ADR-200): the `npm run build` of
  the project it writes puts a Markdown copy next to each page (`operation/getPet.md` beside `operation/getPet/`)
  for coding agents, with `llms.txt` and `llms-full.txt` at the root of the site, for OpenAPI, Swagger 2.0,
  AsyncAPI, Protobuf and GraphQL. `--no-markdown` leaves them out.
- **`apigenie-mcp`** (ADR-202, experimental), a fifth binary installed with the CLI: a Model Context Protocol
  server on stdio for coding agents, with the tools `lint`, `check_breaking_changes` (against a file or a git
  revision), `changelog`, `format`, `bundle` and `describe` (an outline of an API). Each tool but `describe` runs
  `apigenie --json`, and `lint` and `check_breaking_changes` start their result with a one-sentence verdict. It
  writes nothing unless started with `--allow-write`. It works only on files inside the client's roots, else the
  `--root` directories, else its working directory. The Claude Code plugin starts it.

- **`apigenie lint --bundle` and `apigenie diff --bundle`** (ADR-194) bundle the local files an OpenAPI document
  references into it before linting or comparing, as `apigenie bundle` does, so that what the references lead to is
  checked too. Lint issues in bundled content are reported in the file they come from, at their line; diff changes in
  bundled content have no position. A reference to a URL can't be bundled and fails the command; `--bundle` can't be
  combined with `lint --fix` or `diff --update-version`.
- **CloudEvents in AsyncAPI documents** (ADR-205). Messages that are CloudEvents, in structured mode (an
  `application/cloudevents+json` content type) or binary mode (attribute headers such as `ce_id`), are checked as such.
  - The `cloudevents` lint ruleset (`extends: [recommended, cloudevents]`) has three rules:
    `cloudevents/required-attributes` (`id`, `source`, `specversion` and `type` declared and required, also when a
    later trait's `headers.required` replaced a CloudEvents trait's), `cloudevents/binding-headers` (the header
    prefix of the channel's protocol: `ce-` over HTTP, `ce_` over Kafka, `cloudEvents:` over AMQP) and
    `cloudevents/attribute-schemas` (`specversion` pinned to `1.0`, the formats of `time`, `source` and
    `dataschema`, extension names). `standard-media-types` accepts the CloudEvents media types.
  - `apigenie-server` and `apigenie test` report `message.cloudevents.invalid` (`error`) for a CloudEvent without a
    required attribute or with an invalid one, over every transport.
  - The mock gives generated events a UUID `id` (from the seed) and `specversion` `1.0`, and serves a message with
    the content type its traits set.
- **Typed streams in `apigenie-generator client fetch`** (and the client of `server mcp`): an operation with a success
  response in `text/event-stream` or JSON Lines gets a function per format, `getTrackingEventsEventStream()` or
  `getTrackingEventsJsonl()`, returning an `AsyncIterable` of the items typed by `itemSchema` (`x-itemSchema` before
  OpenAPI 3.2). JSON Lines yield one parsed value per line, server-sent events an object with their `data`, `event`,
  `id` and `retry` fields (`ServerSentEvent` without an `itemSchema`); leaving the loop early closes the connection.
- **Webhooks and callbacks in `apigenie-generator server express`**: `src/senders.ts` has `createWebhooks()` and
  `createCallbacks()`, typed senders that send the webhooks of the document and the callbacks of its operations with
  `fetch`. A callback's URL is resolved from the runtime expressions of its key, such as
  `{$request.body#/callbackUrl}`, against the request and response of its operation. A sender validates the
  parameters and a JSON, form or text body first, rejecting with an `InvalidRequestError` instead of sending an
  invalid request or one with a `contentType` the operation doesn't declare. It resolves with a declared response, typed per status, and rejects with an
  `UnexpectedResponseError` for any other.
- **QUERY and other methods in `apigenie-generator server orpc`**: operations with methods other than GET, POST,
  PUT, DELETE, PATCH, HEAD, OPTIONS and CONNECT, such as QUERY with oRPC 1 or an `additionalOperations` COPY, are
  routed instead of skipped with a warning. The contract declares a method missing from oRPC's method type with a
  cast, and the CORS plugin allows it in its answer to a preflight. Node.js answers a request whose method is missing
  from `http.METHODS` with 400.
- **Webhooks and callbacks in `apigenie-generator server orpc`**: `src/senders.ts` has `createWebhooks()` and
  `createCallbacks()`, typed senders that send the webhooks of the document and the callbacks of the procedures with
  `fetch`, like the Express server's senders. A sender validates the parameters and a JSON, form or text body with
  the Zod schemas of `OUTGOING_SCHEMAS`, and rejects with an `InvalidRequestError` instead of sending an invalid
  request or one with a `contentType` the operation doesn't declare. It rejects with an `UnexpectedResponseError` for an undeclared status or media type, or a JSON or text
  body its schema rejects. Its request and response types come from `src/schemas.ts`, such as
  `OnShipmentStatusChangedRequest` and `OnShipmentStatusChangedResponse`. A callback's URL is resolved against the
  input and output of its procedure. Both servers send the requests with the same module, `src/outgoing.ts`, which
  exports the errors and the types of the options.
- **`createRootRouter()` in `apigenie-generator server express`**: a router to mount at the root that serves each
  operation under the path of its first server. An operation uses its own servers, else those of its path item, else
  `BASE_PATH`, so an operation served at the root of another host is routed at the root, not under the document's
  base path. `OPERATIONS` lists the servers of such operations, and the scaffold mounts the root router when the
  operations have paths other than `BASE_PATH`. `createRouter` is unchanged and serves every operation under
  `BASE_PATH`.
- **Multipart bodies in `apigenie-generator server express`**: the router decodes a `multipart/form-data` body
  whose schema has properties into a typed object. Binary parts are `File` objects, object parts JSON and the
  others text converted to their schema's types; array properties collect repeated parts. A file of a media type
  its encoding doesn't allow, invalid JSON and a repeated single part are answered with 400, and the decoded body
  is validated against its schema. Such bodies were left to middleware and typed `unknown`.
- **Streamed responses in `apigenie-generator server express`**: a handler can answer a `text/event-stream` or JSON
  Lines response with an `AsyncIterable` of its items, typed by `itemSchema` (`x-itemSchema` before OpenAPI 3.2). The
  router writes each item as it comes, one JSON line or one event, and calls the iterator's `return()` when the
  client disconnects; `RequestContext.signal` is aborted then too.
- **A macOS installer**: `apigenie-X.Y.Z-macos-arm64.pkg` on the release page installs the five tools into
  `/usr/local/bin` on Apple silicon Macs, with a double-click and an administrator password. It is signed with a
  Developer ID Installer certificate, notarized and stapled, so macOS opens it without a warning, offline too. The
  macOS zip, the Homebrew formula and the npm package are unchanged.
- **The desktop editor's installers on the release page**: API Genie Editor, the desktop editor, now ships with the
  CLI at its version. The release page has `apigenie-editor-X.Y.Z-macos-universal.dmg` for Apple silicon and Intel,
  signed, notarized and stapled. Windows gets `-windows-x64.msi` and `-windows-x64-setup.exe`, not code-signed yet,
  so SmartScreen warns before the first run. Linux gets `-linux-x64.deb`, `.rpm` and `.AppImage`. The release notes
  say which are signed, how to get past SmartScreen, and what the editor needs installed: `apigenie-server` for the
  mock server, and Node.js 20 or later for publishing and subscribing in AsyncAPI "Try it".

### Changed

- **`{{property}}` in custom rules names a missing field by the path from its last existing member, as Spectral
  does**: for a field that doesn't exist, it is the path from the last member that does, such as
  `responses[429].content` or `post.summary`, where it was the last segment alone (`content`, `summary`). The
  messages of the core functions use it, so a missing field now reads `"post.summary" property must be truthy`.
- **A JavaScript function's result path can hold segments of other types, as in Spectral**: a segment that is
  neither a string nor an index, such as a negative number or an array, names the member `String(value)` names,
  where the function failed. A path to a member that doesn't exist is reported at the closest one that does.
- **`apigenie bundle`, `apigenie lint --fix` and `apigenie-server` stop on input that repeats a key in an
  object.** `bundle` and `lint --fix` print `duplicate key "<name>"` and exit with 2, instead of writing the key
  twice. `apigenie-server` prints `Cannot serve 'FILE': duplicate key "<name>"` and exits with 3. The message names
  the key, not its line.
- **A JSONPath dot-notation name ends at `^`** (ADR-217): in the `given` and `field` of lint rules, `$.a^b` is
  now a syntax error; a member name that contains `^` is written in brackets, `$['a^b']`. Overlay `target`
  expressions are unchanged.
- **The Java client and the Spring server leave the generation date out of `@Generated`** (ADR-227):
  `hideGenerationTimestamp` defaults to `true`, so generating twice from the same document gives the same files.
  The annotation keeps the generator version. Set `hideGenerationTimestamp: false` to get the date back; a
  configuration that sets only `generationTimestamp` now needs `hideGenerationTimestamp: false` as well.
- **`apigenie format` lays out JSON output by the `array` and `object` styles**: `flow` writes an array or object
  on one line, with everything inside it. `block` and `best-fit` write one element or member per line, as in YAML
  output. The default `original` styles keep the previous JSON layout, one element or member per line, even for the
  flow collections of a YAML input: JSON keeps no styles, so formatting the output again would change them.
  `style_overrides` still apply to YAML output only.
- **`apigenie-generator server ws` requires the authenticators of secured channels**: when a channel has security
  schemes, `createServer` takes `options` with `authenticate`, an `Authenticators` object with a function per scheme,
  and refuses connections that none of them accepts. Pass an authenticator for each scheme of your channels.
- **`apigenie-generator client python` leaves out internal operations and sends `content` parameters as JSON**:
  operations marked `x-internal` are left out unless `internal_operations` is `true`, and a parameter described with
  JSON `content` is sent as JSON, not with the form style. Strings with a `contentMediaType` other than text or JSON
  are `File` values in requests and `bytes` in responses, not `str`.
- **`apigenie-generator server fastapi` changes the signatures of some interface methods**: `deepObject` and JSON
  `content` parameters are arguments instead of `request`, delimited, non-exploded `form` and header arrays are lists
  instead of strings, and operations secured by mutual TLS take its token and call `validate_<scheme>`, which answers
  501 until a `BaseSecurity` subclass implements it. Request bodies of models with `readOnly` or `writeOnly`
  properties are their `...Input` variant, the model leaves out its `writeOnly` properties, responses whose only
  content is a stream are `AsyncIterator`s of their items, and closed `prefixItems` arrays are `tuple[...]`.
  Update the signatures of existing implementations in `impl/`, which aren't regenerated.
- **`apigenie-generator server go` moves operations with their own server and leaves out internal operations**: an
  operation or path item with `servers` is registered below the path of the first one's URL, not below `BaseURL`, e.g.
  `/health` instead of `/v2/health`. Operations marked `x-internal` are left out of `ServerInterface` and
  `StrictServerInterface`, and webhooks and callbacks marked so get no sender. Set `internal_operations: true` to keep
  them.
- **`apigenie-generator server aspnet` widens some interface methods, moves routes and checks scopes**: operations
  whose responses have several media types return a `Results<...>` with a result per kind, and object and `content`
  parameters are now arguments. Update the signatures of existing implementations in `Apis/*Api.cs`, which aren't
  regenerated. Operations with servers of their own are mapped below the paths of those servers, e.g. `/health`
  instead of `/v2/health`. Operations whose security alternatives all list OAuth 2.0 or OpenID Connect scopes answer
  403 when the user lacks them. `Program.cs` isn't regenerated either: register the senders with
  `builder.Services.AddHttpClient<WebhookSender>()` and one call per callback class.
- **`apigenie-generator server spring` turns `contentMediaTypeAsBinary` on by default**: strings with a non-JSON
  `contentMediaType` and no `contentEncoding` are files and binary bodies, as with `format: binary` and as in
  `client java`. Set the option to `false` for the earlier `String`.
- **`apigenie-generator client fetch` sends an operation to its own server, and leaves out internal and disabled
  operations**: an operation or path item with `servers` other than the document's first one is sent to the first of
  them, not to the configured `baseUrl`; `operationServers: false` in `configure()` sends every request to `baseUrl`
  again. The tools of `server mcp` do the same unless `<PREFIX>_BASE_URL` is set or `--mock` is given, and
  `<PREFIX>_OPERATION_SERVERS` (`true` or `false`) decides either way. Operations marked `x-internal` are left out
  unless `internal_operations` is `true`, and those marked `x-apigenie.codegen.disabled` always.
- **The Swagger 2.0 linter reads documents through their conversion to OpenAPI** (ADR-209). An `operationId` or tag
  `name` that is empty or only whitespace is now an error of reading: `apigenie lint` prints `Operation ID must not
  be blank` or `Tag name must not be blank` and exits with status 2. Before, `operation-id-defined` reported an
  empty `operationId` with status 1, and a whitespace-only `operationId` or a blank tag `name` passed without an
  issue.
- **`x-webhooks` of OpenAPI 3.0 documents are read as webhooks**, as `x-itemSchema` is read as `itemSchema`: the
  linters, `diff`, `changelog` and the generators see them, so linting an existing 3.0 document may report new
  findings in its webhooks. A 3.0 document is written with `x-webhooks` again. In 3.1 and 3.2 documents, and when
  its value isn't an object, `x-webhooks` stays an extension.
- **`apigenie-generator server express` reads multipart bodies itself**: when middleware such as multer has already
  parsed a `multipart/form-data` body whose schema has properties, the router answers with 500 instead of passing
  the body on unvalidated. Middleware that only reads the raw body, such as `express.raw({ type: "multipart/*" })`,
  still works.
- **`apigenie-generator client fetch` reserves `ServerSentEvent`, `AsyncIterable` and `requestStream`**: `index.ts`
  exports the runtime's `ServerSentEvent` type and the stream functions return `AsyncIterable`, so a component
  schema named `ServerSentEvent` or `AsyncIterable` is now generated as `ServerSentEvent2` or `AsyncIterable2`, and
  an operation named `requestStream` as `requestStream2()`.
- **`apigenie-generator server express` reserves `ServerSentEvent` and `AsyncIterable`**: `index.ts` exports the
  runtime's `ServerSentEvent` type and the response types of streamed media types use `AsyncIterable`, so a
  component schema with either name is now generated as `ServerSentEvent2` or `AsyncIterable2`.
- **`apigenie lint` is faster on large OpenAPI documents, and `apigenie lint --fix` much faster.** Checking the
  local references of the schemas no longer maps every value of the document to its JSON pointer, which took a
  fifth of the time of linting the GitHub specification, and `--fix` runs only the rules that offer fixes before
  applying them, then every rule once on the fixed document: about 40 percent less time. The reports and the fixed
  files are the same as before.

### Fixed

- **`apigenie bundle` puts the referenced content in place of a component that only references its own name in
  another file**: `PhoneNumber: {$ref: common.yaml#/components/schemas/PhoneNumber}`, as CAMARA's APIs write
  their common schemas, becomes the `PhoneNumber` schema of `common.yaml`. The OpenAPI and Swagger bundles
  kept the reference and copied the schema next to it as `PhoneNumber_2`, which naming rules such as
  `camara-schema-casing-convention` reported. Commands that bundle a document before reading it do the same:
  `apigenie changelog`, `apigenie-generator docs` and, for OpenAPI documents only, `apigenie lint --bundle`,
  `apigenie diff --bundle` and `apigenie-server`. AsyncAPI bundles already put the content in place of any
  component that references another file, whatever its name.
- **Custom rules report an issue whose path goes through a `$ref` at the definition it references**, as
  Spectral does. `apigenie lint` reported it at each reference, so a shared definition that breaks a rule was
  reported once per use. The OpenAPI, AsyncAPI and Swagger linters now report it once, at the definition, and
  its path and `{{path}}` name the definition too. Rules with `resolved: false` are unchanged.
- **The JSON Schema of the `--formatter json` report allows the `hint` severity**: `apigenie lint` reports
  hints, as the reference says, but `apigenie-lint-report.json` allowed only `error` and `warning`, so a
  report with a hint failed validation against it.
- **`apigenie-server --log-format json` writes `proxyValidation` once in its startup line**: with
  `--proxy-to mqtt://...` and no WebSocket or HTTP target, the line repeated the key.
- **`apigenie convert` keeps the first Swagger 2.0 definition of a name `definitions` repeats**, the one
  references already resolved to, and leaves out the later ones. All of them went into `components/schemas`,
  which then had the name more than once. `apigenie-server`, `apigenie test --spec` and `apigenie-generator`
  do the same when they convert a Swagger 2.0 file in memory. They report each left-out copy at the line of
  the definition they keep.
- **`.openapi-generator/FILES` of `server spring` and `server fastapi` no longer changes when the code is generated
  again** (ADR-227): it lists the controllers, the implementation package and the tests that exist and are kept, as
  it does when they are first generated.
- **`apigenie-generator server phoenix` requires a client certificate for `mutualTLS` security schemes**: a
  connection without one was accepted as presenting the credential.
- **`apigenie-generator client elixir`, `server phoenix` and the other Elixir generators keep a colliding module name
  that ends in a digit in PascalCase**: a second `PetOption1` is now `PetOption1V2` instead of `PetOption1_2`, which
  Credo's `ModuleNames` check rejects. Regenerating renames such modules: update code that refers to the `_2` names.
- **`apigenie lint` checks AsyncAPI documents whose servers, channels or messages are in other files** instead of
  stopping with "Unspecified error". The rules skip what the other file holds.
- **`patternProperties` in the TypeScript types of `apigenie-generator client fetch`, `server express`, `server
  mcp`, `client kafkajs` and `server kafkajs`**: when `additionalProperties` is `false` or a schema
  object, the properties an object doesn't list are typed by its `patternProperties` too. An object with
  `additionalProperties: false` whose keys follow patterns (`patternProperties: { '^dhl$': ..., '^ups$': ... }`) was
  generated as `Record<string, never>`, which allowed no property. It is now a `Record` of the union of the pattern
  schemas' types.
- **`apigenie lint` and `apigenie diff` check OpenAPI documents with references to other files** (ADR-194) instead
  of stopping with "unresolved reference" (exit status 2).
  - The lint rules check what the file holds. A rule about keys checks a path or a response in another file too,
    and the others skip it. `path-parameters-defined` and `path-parameters-on-items` don't report path parameters
    that a parameter in another file may define.
  - `diff` compares such a reference, and a schema `$ref` to another file, by its `$ref`: the same one is no
    change, and another one is a `reference.$ref` change, `breaking` by default. An added or removed item in
    another file follows the rule of its place, with the strictest facts (a parameter may be required).
    `reference.$ref` now takes `add`, `remove` and `modify` rules. The changelog lists a parameter in another
    file by its `$ref`, in the location `$ref`.

- **`openapi-json-schema-validation` accepts Path Item `$ref`s in OpenAPI 3.1 documents** (ADR-195, ADR-196). 3.1
  documents are validated against the official 3.1 schema of 2026-08-03 instead of the 2022-10-07 one, whose Path
  Item had no `$ref`: every path under `paths` that referenced another path item was reported as "property was
  not successfully evaluated". The newer schema also accepts server URL templates such as
  `https://{region}.example.com` and the Link Object's `server`. As the specification says, it rejects `example`
  and `examples` side by side in a parameter, header or media type, and unknown fields next to the `$ref` of a
  webhook, a component path item or a callback, which went unchecked before.

- **`openapi-json-schema-validation` accepts a comma-separated list of media ranges in an Encoding Object's
  `contentType`**, such as `image/png, image/jpeg`, as the OpenAPI 3.1 and 3.2 specifications allow
  (ADR-196). 3.0, 3.1 and 3.2 documents are validated against the official schemas of 2024-10-18, 2026-08-03
  and 2026-08-30, which no longer check `contentType` for a single media range. The 3.2 schema requires the
  names of response headers, encoding headers and header parameters to be tokens (RFC 9110), and rejects
  braces in the name of a path parameter described by `content`. The 3.0 schema allows extensions in an
  Encoding Object, as `jv_schema`'s edited copy of the 2021-09-28 one did.

- **`operation-id-defined` and `operation-id-unique` count an operation shared through a Path Item `$ref`
  once.** An operation of a component path item that paths or webhooks reference was reported once per
  reference, so `operation-id-defined --fix` failed with "conflicting edit", and `operation-id-unique`
  reported the operation's own ID as a duplicate. The generated ID is named after the first path that uses
  the operation, else the first webhook, else the component.

- **`apigenie lint` no longer stops with "Unspecified error." on documents that nest too deep or expand aliases too
  far in parts the reader skips**, such as a recursive YAML alias under an unknown property or deep JSON in a
  3.2 `components.mediaTypes` entry. The rule that walks them, `openapi-json-schema-validation`, checks such
  documents completely, and the other rules still run. A rule of the AsyncAPI and Swagger linters whose walk
  exceeds the limits reports "Cannot check the document: it exceeds the nesting or alias-expansion limits" next
  to what it found before.

- **JSON Schemas that declare a dated OpenAPI dialect load**: `$schema` with
  `https://spec.openapis.org/oas/3.1/dialect/2024-11-10` (the default `jsonSchemaDialect` of the current 3.1
  schema), `.../3.1/dialect/2024-10-25`, `.../3.2/dialect/2025-09-17` or `.../3.2/dialect/2026-02-26` failed
  with "unknown dialect", for example in `apigenie-generator schema zod`. They load as
  `https://spec.openapis.org/oas/3.1/dialect/base` does.

- **`operation-id-defined` and `operation-id-unique` check the operations of callbacks**, those of
  operations and of `components.callbacks`. The specification requires an `operationId` to be unique among
  all operations of the API, callbacks included. `--fix` names a callback operation after its callback
  (`postCallbackOnEvent` by default), and an operation shared through a `$ref` is still counted once.

- **The `apigenie diff` changelog lists an operation of a shared path item once, under its path.** An
  operation added, removed, modified or deprecated in a component path item that the last changed path
  references was listed again under that path's URL, for each webhook and for the component sharing it, in
  every formatter. The operations of component path items and webhooks are API operations only through the
  paths that reference them. A deprecated operation whose callback changed is no longer listed with the
  callback's method.

- **`unused-shared-component --fix` keeps the security schemes that security requirements name.** It used to
  remove them, though the check didn't report them.

### Desktop editor

- The right pane has no Code tab. *Show as code* on a file's root form, such as the *Specification* row's, shows the
  whole file as wide as the pane. While a file has syntax errors, its forms offer *Show the file as code*. A file
  picked in the file list opens its root form. The code no longer follows the tree's selection, and its cursor no
  longer selects in the tree.
- With one spec open, the tree starts with a *Specification* row that opens the whole spec's form: its version
  and its sections. The form is headed *Specification*, in place of *Document*.
- In a schema's rows, the type menu keeps its width and the description takes the rest. A long component name
  among the menu's references made the menu as wide as the name.
- A long form, such as an operation's, lists its sections beside it: pick one to go to it, or *Overview* to go back
  to the start of the form. The list marks the section you are reading and hides when the form is narrow.
- AsyncAPI's forms, such as a message's, list their sections as well.
- A schema's form lists its sections too: the details of the row shown, in groups (Values, Limits, Flags,
  Composition) now headed in the details panel, and the keys edited as code.
- Each key a form has no field for, such as `externalDocs` or a parameter's `style`, is a section of its own,
  named after the key and edited as code, in place of one *Other fields* section.
- The forms' section headings, such as Parameters, Request body, Responses and Messages, are bands with an accent
  edge, set apart from the fields above them.
- The parameters table's *In*, *Required* and *Schema* columns grow with their text in Safari and the macOS app, where a
  header parameter's *header* ran into *yes*.
- The code view, *Show as code* and the text diffs use CodeMirror in place of Monaco: the
  app's code is less than half its former size, about 4.5 MB instead of 10 MB. Completion and hover still come from
  the spec's structure, and now work while the line you type is not valid YAML yet. The editor's colours follow
  the app's light and dark palettes.
- YAML is highlighted in the code view and in a form's *Show as code*.
- File › Close Spec (Ctrl+W, Cmd+W on macOS) closes the open spec and the files it brought, asking about unsaved
  changes first. The editor is then as it starts with no spec.
- A *New spec…* button joins the toolbar. With no spec open, it asks for OpenAPI 3.1 or AsyncAPI 3.0, as File ›
  New… does, then where to save the spec. The editor writes the spec there and opens it.
- File › Open Recent lists the last ten specs opened, then Clear Recent. Started without a spec on the
  command line, the editor opens the newest one that still exists.
- Files changed on disk, by a `git checkout` or another editor, are read again when you come back to the window.
  A file with unsaved changes keeps them: the status bar names it, and Save writes over the version on disk. A
  file deleted on disk is named in the status bar.
- A View menu shows and hides the Side Bar (Ctrl+B), the Panel (Ctrl+J) and the Right Pane (Ctrl+Alt+B); on
  macOS, Cmd+B, Cmd+J and Cmd+Option+B. With the panel closed, the form and the right pane now reach the status bar.
- *Export bundled* works in the desktop app for OpenAPI specs, and the Changes tab shows the API changes there.
  The installers now carry `openapi_bundle`, `openapi_diff` and `asyncapi_diff`, compiled to WebAssembly.
- The splitters between the panes are thicker, with a grip in the middle.
- A path's template and its path parameters change together in the forms. Each change is one undo step. A
  change that would give the path another path's template is refused, and nothing changes.
  - Setting a parameter's *In* to *path* makes it required and adds `/{name}` at the end of the template.
  - Renaming a path parameter renames its `{name}`, and the other path parameters of that name in the path and
    its operations. A name another path parameter already has is refused.
  - Removing a path parameter, or setting its *In* to another place, takes `{name}` out of the template
    (`/pets/{id}` becomes `/pets`). It stays when another path parameter of the path or its operations has that
    name.
  - The path's form and an operation's form do all three. A parameter's own form renames it and sets its *In*.
  - Editing the template in the path's form renames, adds or removes path parameters to match. A new `{name}`
    gets a required string path parameter on the path. When as many `{name}`s go as come, they are read as
    renames, in order.
  - Renaming a path parameter or editing the template leaves the parameters taken by `$ref` as they are.
    A rename then keeps their `{name}`, and a `{name}` of theirs renamed in the template gets a new path
    parameter.
  - In the path's form, a path parameter of the path or its operations that the template lacks has a button,
    *Add {name} to the template*, which adds `/{name}` at the end.
- The tree lists these sections even when the spec lacks them: Servers, Tags, Paths, Webhooks (3.1 only) and
  Components in OpenAPI; Servers, Channels, Operations, Messages and Components in AsyncAPI. Each section,
  and each component section under Components, has a *+* that adds an entry and selects it, so that its form
  opens. A section the spec lacks is created with that entry. The *+* of Components asks which kind of component
  to add. The right-click menu has the same items, such as *Add server*, *Add operation…* and *Add schema*, and
  Insert on a focused row does what its *+* does. Shift+F10 opens that menu on keyboards without Insert.
- The *+* of Paths asks for the method and the path of a new operation, and offers the paths the spec has, so
  that one path can get several operations (`GET /pets` and `POST /pets`). A new path is created with its
  operation. The right-click menu of an operation, and of a path without operations, has *Add operation to
  /pets…*, which starts with the path's first free method, and Insert on such a row opens it too. Adding a
  method the path already has, or a path of the same shape as one the spec has (`/pets/{petId}` beside
  `/pets/{id}`), says so.
- The forms of a path item (a path, a webhook, a callback's path or one under Components) and of an operation
  have *Delete…* in their header. It asks first, names the references that would break, deletes as one undo
  step and opens what held the deleted entry. The right-click menu of an operation under Paths has *Delete path
  /pets…* too, since the tree lists a path with operations only through them; for a path that is a `$ref`, it
  deletes the path and keeps what the path refers to.
- The forms of a tag, a server and every component (a schema, response, parameter, example, request body,
  header, security scheme, link or callback, in AsyncAPI too) have the same *Delete…*. Deleting a tag leaves
  the operations that list it as they are, and the confirmation says how many do.
- A server variable's *Values* are chips, as an operation's tags are: Enter or a comma adds a value, its × removes
  it.
- A schema's *Allowed values* are chips, as a server variable's values are. In a numeric or boolean schema a typed
  `3` or `true` is added as a number or a boolean, and the values already in the file keep their types. An object
  or array schema keeps the YAML text field.
- Values chips no longer leave an empty line under them: the input after the chips takes what is left of their line.
- Every example box (a schema's or a property's example, an Example object's value, a media type's and a
  message's examples) has a copy button in its top right corner. It copies the example as shown, JSON or YAML.
- A form's header shows where its node is, from the file down (*openapi.yaml › Paths › /pets › GET ›
  Responses › 200*), in place of its JSON pointer, which is now the tooltip. Each step opens that node's form.
- The parameters tables of a path and an operation size their columns to what they hold: *In*, *Required* and
  *Schema* are as narrow as their content, *Name* takes a fifth of the width and *Description* the rest.
- The tree's sections each have an icon (Info, Servers, Tags, Paths, Webhooks, Components, Channels, Operations,
  Messages), and so do the spec, shared-file and import-only groups.
- Example fields show the value as JSON, with a switch to YAML that is kept for the next examples. These are the
  Example of schemas, parameters and media types, an Example's Value (formerly *Value (YAML)*), and a message
  example's payload and headers. A value with `.inf`, `.nan` or a recursive alias, which JSON can't hold, stays in
  YAML. Either is read back, and the file keeps its own style.
- A schema's details show its Description, in Markdown with a Write / Preview switch.
- A schema row's type menu offers one of, any of and all of, and a reference to each component schema.
  A schema the menu cannot show (several types, `not`...) reads *complex*, and *Edit in code* opens it in
  the code view.
- The Example field of a schema's details is multi-line, and the other YAML fields there keep the lines of a
  mapping or a list: a generated object example no longer shows (and saves) as one joined line.
- An operation's tags are a multi-select: chips that remove themselves, and an input that adds a tag,
  suggesting the declared ones.
- The Problems panel filters by severity (Errors, Warnings, Info, Hints), and keeps the choice.
- A form shown as code fills the height of the form pane.
- The file list is headed *Spec and referenced files*, and the form's Raw section is split into *Other fields*
  and *Extensions*.
- The desktop app lints OpenAPI documents with API Genie's own linter (the rules of `apigenie lint`), in the
  Problems tab and under the fields, with its quick fixes: the installers now carry it, compiled to
  WebAssembly. Until now only the web editor had it.
- The linters read `commands.lint` of the project's `apigenie.yaml`, and `commands.lint.asyncapi` for AsyncAPI.
  The editor takes the file nearest to the spec, as `apigenie lint` run in the spec's folder finds it. It looks in
  the spec's folder on the desktop and the workspace folder in VS Code; in a browser, among the dropped files. On
  the desktop and in a browser, *Allow access to their folder…* widens that to a folder above the spec. Rulesets, severities and custom rules apply in the editor. A configuration the linter refuses is an error
  on the configuration file in the Problems tab, and then the default rules apply. Custom JavaScript functions don't
  run yet: the rules that call them are left out, with a warning. In VS Code an edit to the file applies as you
  type; elsewhere a change applies when the spec is opened again.
- The linters read the ruleset files that `extends` names in `apigenie.yaml`, and the files those extend
  (ADR-217): from the spec's folder on the desktop; in a browser, from a folder allowed with *Allow access to their
  folder…*, or in Safari and Firefox among the dropped files when they sit beside `apigenie.yaml`. Their functions
  are left out with the rules that call them, and a warning says so. When a ruleset file
  extends a ruleset the editor's linter doesn't have (`spectral:oas`, `owasp`, an npm package), that ruleset is
  left out with a warning. A ruleset file's `aliases` and `overrides` are skipped with a warning too. An `extends`
  entry with an absolute path, or a relative path more than 8 folders up, is an error on that entry, and so is a
  ruleset file that can't be read or doesn't parse. The default rules then apply.
- AsyncAPI documents are linted with API Genie's AsyncAPI linter (the rules of `apigenie lint` for
  AsyncAPI), with its fixes, in every host.
- The editor no longer runs Spectral's rulesets (`spectral:oas`, `spectral:asyncapi`) or a `.spectral.yaml`. The
  Problems tab shows the findings of API Genie's linters under their own rule names, without Spectral's second
  report of the same problems. Spectral rules with no counterpart in API Genie are no longer reported. To keep a
  `.spectral.yaml`'s rules, move them to `apigenie.yaml`: see
  [Migrate from Spectral](https://apigenie.pl/docs/guides/migrate-from-spectral). A Spectral ruleset (`.spectral.yaml`,
  `.yml` or `.json`) with no configuration file in the spec's folder or above it gets an info finding that names
  that guide.
- AsyncAPI documents are checked by API Genie alone (ADR-212): the AsyncAPI parser's findings are gone, and
  what it checked comes from API Genie's AsyncAPI linter, which gains 5 rules for the parser's core checks it
  lacked (`apigenie lint` reports them too). A structure error in another file of the spec shows on that file,
  where the error is.
- The AsyncAPI docs preview shows API Genie's own AsyncAPI docs, as `apigenie` publishes them: the overview,
  servers and security of the spec, or the operation, channel or message selected in the tree or the code
  view. It no longer loads the official AsyncAPI renderer, and the editor carries no React.
- The editor opens specs, not folders (ADR-197). *Open folder…* is gone: *Open spec…* (File › Open Spec…,
  Ctrl+O, on the desktop) opens a spec with the files it refers to. The desktop app starts on a spec given on
  its command line (`apigenie-editor openapi.yaml`), dropped spec files open in the browser, and a dropped
  folder is refused. A new file never overwrites a file on disk the editor did not read: suggested names skip
  it, and Save refuses and says why.
- *Open spec…* opens one spec and the files its references reach, read as references name them, also
  after an edit adds one (ADR-197). Files that can't be read are listed under the file list, with *Allow
  access to their folder…* on the desktop and in Chromium browsers. In VS Code, the document is the spec
  and only the files it reaches join it.
- The opened spec is the file being edited (ADR-197). The other files are referenced: shown in the tree, the
  file list (under Referenced), the code view and Problems, but read-only, with *Edit this file* to change
  one.
- Path parameters have no Required checkbox: they are always required, and moving a parameter into the
  path sets `required: true` with the change.
- Schema findings on examples, bindings and Try it name the field as code reads it (`[0].owner: Unexpected
  property 'age'`) instead of a JSON pointer and Ajv's message.
- The editor fits its window: in a short window the bottom panel gives way, and the page never scrolls.
- A tag's form lists the operations that have the tag, each a link to its form.
- My schemas in the Library are editable: *Edit* opens one in the schema editor and the code view, and
  every change is kept in the library at once, with nothing to save.
- The Flow tab shows only while the current file is an AsyncAPI spec.
- A panel under the form and the right pane, as in VS Code, with a Problems tab: every finding of the
  folder by file, with its rule and line, a filter, and a click that goes to the node. The status bar's
  error and warning counts show and hide it, and its height is resizable. The tree and the file list no
  longer show problem counts.
- The theme switch in the toolbar is one icon button that steps through the system's palette, light and
  dark.
- The app icon is the website's favicon, the genie over the word API, in the desktop shell and as the web
  editor's favicon.
- Restyled forms: sections with headings, short fields side by side, Write and Preview tabs opening into
  the description's bordered text box, quiet add and remove buttons, aligned table rows, tags and servers as pill toggles,
  and the operation's method badge. The schema editor draws guide lines from each schema to its
  properties and branches, and its Details panel puts paired keywords side by side.

- Splitters between the panes: drag the borders between the side bar, the form and the right pane,
  and between the outline, the files and the Library, to resize them. Arrow keys move a focused
  splitter, a double-click or Enter puts its pane back to the default size, and the sizes are kept
  for the next visit.

- A menu bar: File (New…, Open Folder…, Open File…, Save, Save As…, Exit) and Edit (Undo, Redo), with
  their shortcuts; on macOS, About and Quit are in the application menu and Edit has Cut, Copy, Paste
  and Select All. New… starts an OpenAPI 3.1 or AsyncAPI 3.0 spec in the open folder; Open File…
  opens the file's folder with the file selected; Save As… writes the current file anywhere on disk.
- Closing the window, quitting, or opening another folder with unsaved files asks whether to save
  them first.
- The web editor at https://apigenie.pl/editor/, deployed with the website: the same bundle as the
  desktop shell's, with the repository's WebAssembly modules. The status bar and About show the commit
  the editor was built from.
- About, in the toolbar: the editor's version, the app's, and where to read what each host offers
  (the website's "The editor's hosts" page).
- The app opens a folder given on its command line (`apigenie-editor <folder>`).
- The desktop shell: the editor in its own window on macOS, Windows and Linux, opening folders in
  the native dialog and saving to them in place.
- Try it for AsyncAPI operations: publish a message, with its payload and headers checked against
  the message's schemas first, or subscribe and watch what arrives, on the operation's Kafka, AMQP,
  MQTT or WebSocket servers. Needs Node.js 20 or later on the machine.
- A mock server for OpenAPI specs, started from the toolbar: `apigenie-server` serves the spec as it
  is in the editor, saved or not, on this computer, and answers and validates requests as it does on
  the command line. Try it out in the preview can send to it, and its log shows each request and what
  didn't match the spec. Needs API Genie 0.11.0 or later installed
  (`npm install -g @mykulyak/api-genie` or `brew install mykulyak/apigenie/apigenie`), or
  `APIGENIE_SERVER` set to the `apigenie-server` binary.

## 0.11.1 (2026-11-01)

A maintenance release with no changes to the tools: 0.11.1 republishes 0.11.0 to check the new local release flow.

## 0.11.0 (2026-11-01)

A Claude Code plugin, released with the CLI, makes coding agents lint every API description they edit and check
it for breaking changes. `apigenie convert` downgrades JSON Schema to draft-07, draft-04 and OpenAPI 3.0, and the
linters gain a rule for poorly supported schema keywords and an opt-in `privacy` ruleset.

### Upgrading

- **`apigenie-mock` is gone: run `apigenie-server`.** The deprecated name of the server (ADR-147) is no longer
  installed by any archive or package; scripts, Dockerfiles and CI jobs that still call `apigenie-mock` need the
  new name.
- **`apigenie generate`, `apigenie mock` and `apigenie catalog` are unknown commands.** They no longer print the
  binary they moved to; run `apigenie-generator`, `apigenie-server` and `apigenie-catalog`.
- **The naming rules of the OpenAPI, AsyncAPI and Swagger linters take the convention names of the GraphQL
  linter.** `parameter-naming`, `schema-enum-naming` and `schema-property-naming` accept `camelCase`,
  `camelCaseStrict`, `PascalCase`, `PascalCaseStrict`, `snake_case`, `kebab-case`, `CONST_CASE` (or `UPPER_CASE` and
  `SCREAMING_SNAKE_CASE`) and `Header-Case`. The short names `camel`, `camel-strict`, `pascal`, `pascal-strict`,
  `snake`, `kebab`, `const` and `header` are configuration errors now (`Unknown naming convention: camel`); rename
  them in `commands.lint`. The defaults are unchanged, and so is the Spectral `casing` function's `type`.

### Added

- **A Claude Code plugin** (`distribution/claude-code`, ADR-182), released with the CLI and carrying its version.
  - A skill teaches coding agents the API Genie loop: lint after every spec edit, check breaking changes with
    `apigenie diff` before calling a change done, mock with `apigenie-server`, and generate with
    `apigenie-generator`.
  - A hook lints each OpenAPI, Swagger, AsyncAPI, GraphQL or Protobuf file Claude edits and reports only the
    findings the edit added.
  - The commands are `/api-genie:lint`, `/api-genie:breaking` and `/api-genie:mock`.
  - Install it with `/plugin marketplace add` on the folder.
- **`apigenie convert --from jsonschema --to draft7|draft4|openapi30` (experimental) downgrades JSON Schema
  documents.** A schema of draft 2019-09 or 2020-12 becomes a draft-07 or draft-04 document, or a Schema Object of
  OpenAPI 3.0. The main rewrite is composition: a schema with `allOf` and `unevaluatedProperties` becomes one flat
  object schema with `additionalProperties`, the members' `properties`, `required`, `patternProperties`,
  `propertyNames`, `minProperties`, `maxProperties` and `dependentRequired` merged into it, local `$ref` members
  inlined (chains and nested `allOf` followed) and the definitions kept for other references. A member that can't be
  merged (`additionalProperties: false`, `anyOf`, `oneOf`, `if`, `enum`, a `discriminator`, a reference to another
  document, a cycle) keeps the `allOf`, drops `unevaluatedProperties` and says why on the standard error, as does a
  property two members define differently (kept as an `allOf` of both). The other keywords follow the target:
  `$defs` becomes `definitions` (references follow), `prefixItems` a tuple `items`, `dependentRequired` and
  `dependentSchemas` `dependencies`, `$dynamicRef` `$ref`; below draft-06 `const` becomes `enum`, numeric exclusive
  bounds the boolean form and boolean schemas objects; for OpenAPI 3.0 `null` types and alternatives become
  `nullable`, `examples` `example`, exact-match `patternProperties` `properties`, and a `$ref` with siblings is
  wrapped in `allOf`. What has no counterpart (`if`, `contains`, `propertyNames` and `dependentRequired` below
  draft-07; `minContains`, `$anchor`, `$vocabulary` everywhere) is dropped with a note. `--from` is optional: a
  document without `swagger` is a JSON Schema. The library is `src/jsonschema_convert`; the design is ADR-180.
- **A lint rule for poorly supported schema keywords: `schema-keyword-support`**, in the OpenAPI and AsyncAPI
  linters (off in `recommended` and `strict`, a warning in `all`). It reports the keywords, and value forms, that the
  configured targets don't support, with the rewrite where one exists: `prefixItems`, `unevaluatedProperties`,
  `$dynamicRef`, `dependentRequired`, `if`, `contentSchema`, `const`, `type` arrays, numeric `exclusiveMinimum`,
  `nullable`, `$ref` with constraining siblings and more. The targets are `draft4`, `draft6`, `draft7`,
  `draft2019-09`, `openapi30` and `codegen` (the keywords most code generators ignore, the default); the options
  take a target, a list of targets, or `targets` and `allow` (keywords never reported).
- **A `privacy` lint ruleset for OpenAPI: no credentials or personal data in URLs.** `extends: [recommended, privacy]`
  adds two rules that look at path and query parameters, the properties of object parameters, and `format`:
  - `privacy/no-credentials-in-url` (error) reports passwords, tokens, API keys, session ids and the like, and
    `apiKey` security schemes with `in: query` (OWASP API2:2023, CWE-598). Paging cursors such as `pageToken` are
    not reported.
  - `privacy/no-personal-data-in-url` (warning) reports e-mail addresses, names, dates of birth, phone numbers,
    national identifiers, bank and card numbers, and special categories of personal data (GDPR Art. 4(1), 9, 10).
  - Both take `allow` (names never reported) and `terms` (more names to report).
- **The `openapi`, `openapi_i18n` and `asyncapi_i18n` WebAssembly modules have a browser flavour**
  (`<name>.web.mjs` and `<name>.web.wasm`, for browsers and workers), like the other modules in `src/wasm`.

### Changed

- **Seeded mock data is the same on every platform, and differs from earlier versions.** `apigenie-server --seed`,
  `apigenie-generator` data and the other users of the schema value generator chose numbers, string and array
  lengths, enum values, `oneOf` branches, optional properties and nulls, and simulated latencies and failures, with
  the C++ standard library's distributions, whose values differ between Linux, macOS and Windows. They now sample
  mt19937_64's raw output with algorithms of their own, as faker already did, so a seed gives the same data
  everywhere; the values of a given seed change on every platform. Faker's own values do not change.

- **The links to the documentation lead to the new addresses of the website** (ADR-183). Lint reports (`html`,
  `sarif`) link each rule under `https://apigenie.pl/docs/linter/<standard>/rules/<rule>`, `--version` the
  compatibility policy at `https://apigenie.pl/docs/reference/cli/compatibility`, and the configuration schema
  the configuration reference at `https://apigenie.pl/docs/reference/cli/configuration`. The old addresses
  redirect to the new ones.

### Removed

- **`apigenie-mock`, the deprecated name of `apigenie-server` (ADR-147).** The archives, `.deb`, `.rpm`, Homebrew
  and the npm package no longer install it; run `apigenie-server`. The `APIGENIE_MOCK_*` variables and the
  `apigenie-mock.yaml` configuration file still work until 1.1.
- The hints `apigenie generate`, `apigenie mock` and `apigenie catalog` printed, naming the binary that took the
  command over (ADR-123, ADR-147, ADR-160).

### Fixed

- **OpenAPI linting reports missing local schema `$ref` targets** (#1014).
  `openapi-json-schema-validation`, enabled in `recommended`, `strict` and `all`, reports an
  unresolved reference at its `$ref` value. Local JSON Pointers and anchors respect schema `$id`
  resources; recursive references remain valid, and example data and external references are
  not checked.

- **Phoenix server READMEs name a generated behaviour in their configuration example** (#1015),
  rather than always naming `Pets`. The example follows tag filtering and normalization, uses
  `Default` for untagged operations, and is omitted when no behaviours are generated.

- **Unsupported numeric configuration versions are reported on one line** (#1016).
  `apigenie config check` no longer inserts a line break inside the quoted value for
  `version: 1.0`; the version must still be the string `'1.0'`.

- **OpenAPI version changes use the configuration property name in diff reports** (#1017).
  Detailed reports now say `openapi.openapi` instead of `openapi.specVersion`, and their JSON
  `config_key` is `openapi`, matching the rules table and the existing configuration.

- **The rule links of the AsyncAPI, Swagger, GraphQL and Protobuf linters lead to their rules.** The website
  publishes the rules and rulesets of all five linters; the links of the AsyncAPI and Swagger linters led to
  the OpenAPI rules, those of the GraphQL and Protobuf linters and of the `privacy/*` rules to no page.

- **YAML output of strings that are not UTF-8.** Neither reader validates its text, so a JSON or YAML string with
  a stray byte (`"single\x9d"`) reached the YAML writer, which read past the end of the string, escaped the byte as
  another character, or wrote it raw. `apigenie format` and `convert` now write every ill-formed UTF-8 sequence of
  a string, a key or a comment as U+FFFD (one per maximal subpart), as the XML writer does (ADR-129); a comment
  also gets U+FFFD for a control character or a line break it cannot hold.

- **Generated values keep the bounds of a property that `allOf` members define twice.** When one member gave a
  property `type: array` and a later one only `maxItems: 1` (or `maxLength`, `minimum` and other keywords that imply a
  type), the mock and `apigenie-generator` used the first definition and could make arrays that were too long.

- **`standard-response-codes` accepts the `default` response.** It reported every `default` entry of a Responses
  Object as a non-standard response code (#1012).

- **Three OpenAPI rules that reported nothing now check what their pages describe (#1013).**
  - `schema-example-defined` (in `recommended`, `strict` and `all`) reports an object, an array or a string with a
    `pattern` without an example, among the entries of `components/schemas` and the inline schemas of media
    types, parameters and headers; an example on the media type, parameter or header counts too.
  - `json-api/resource-type-unique` reports a resource object of a JSON:API response whose `type` is not a `const`
    or a one-value `enum`, and two resource objects with the same type.
  - `json-api/schema-validation` checks the shape of JSON:API request and response documents and their resource
    objects. It was not registered at all; it now is, and joins the `json-api` ruleset.

- **`apigenie format` names a discovered configuration file in its configuration errors.** When the file came
  from the search for `apigenie.yaml` instead of `--config`, the `Invalid format configuration in '...'` message
  read the absent option (#1010).

## 0.10.0 (2026-10-25)

The mock server is now `apigenie-server`, with a document store for CRUD resources and several services in one
process, and a fourth binary, `apigenie-catalog`, keeps a repository's API catalog. `apigenie-generator` applies
OpenAPI overlays before generating, and the three binaries share one table of exit statuses.

### Highlights

- **`apigenie-server`**, the mock server and validating proxy under its new name, with a dashboard at
  `/__apigenie/ui` (Traffic, Operations, Scenarios, Contract, Data and, for AsyncAPI, Channels), several services on
  one port with a prefix each, a document store (`ctx.db`, `db.crud: auto` resources, seeding, snapshots), session
  recording and replay (`--record DIR`, `--replay DIR`), client certificates, MQTT 5 properties, and validating
  proxies for Kafka (`--proxy-to kafka://`) and AMQP (`--proxy-to amqp://`) brokers.
- **`apigenie-catalog`** (experimental), a fourth binary: `catalog list` finds the API specifications of a
  repository and `catalog init` records them in `apigenie.yaml`.
- **Code generation:** `--overlay FILE` on every OpenAPI and AsyncAPI target; the Elixir family (`client elixir` and
  `server phoenix` for OpenAPI and AsyncAPI, `server absinthe` for GraphQL, `server elixir-grpc` and the Elixir gRPC
  client for Protobuf); `server mcp` (experimental), a Model Context Protocol server from an OpenAPI document;
  `server orpc` at the conformance bar.
- **`apigenie test`** speaks Kafka and AMQP (`KAFKA` and `AMQP` regions), GraphQL subscriptions over graphql-ws,
  gRPC client and bidirectional streams, MQTT 5 and mutual TLS.
- **Towards 1.0:** one table of exit statuses for the binaries, `formatVersion` in every JSON report with published
  JSON Schemas, a JSON Schema for `apigenie.yaml` behind `apigenie config`, `config check` and `config schema`,
  configuration discovery without `--config`, the Compatibility page, and experimental labels on what is outside
  the coming promise.
- **Linting and diffing:** the OpenAPI format registry as the list of formats, with `schema-format-deprecated`,
  `schema-format-unknown` and a `hint` severity; `diff` knows sunset dates and no longer rates deprecating as
  breaking; `apigenie evolve plan OLD NEW` (experimental) plans an expand/contract migration.
- **Also:** `convert --from wsdl --to openapi31`, `i18n check` and `i18n sync`, OpenAPI formatting at every depth with
  layout options, Windows console colors, and a docs package published as `@mykulyak/apigenie-docs`.

### Upgrading

- **Upgrading from 0.9: `apigenie-mock` is now `apigenie-server`.** The mock server and validating proxy is
  installed as `apigenie-server` by every archive and package, the npm package and Homebrew, and its Docker image is
  `mykulyak/apigenie-server`. The old names keep working until 1.1, each with a one-line deprecation notice on
  standard error: `apigenie-mock` is a symlink to `apigenie-server` (a copy in the Windows archive, a command of the
  npm package), and the `APIGENIE_MOCK_*` variables are read when the `APIGENIE_SERVER_*` variable of the same name
  is unset. The last `mykulyak/apigenie-mock` image (`latest` and this version) only prints the new name and exits
  with 2; older tags are unchanged. `apigenie-server.yaml` is read before `apigenie-mock.yaml`, which still works;
  `commands.mock`, the `x-apigenie-mock` extensions, the `X-Apigenie-Mock-*` headers and the `/__apigenie` admin API
  are unchanged. What the server sends says `apigenie-server` instead: the `Server` and `Via` headers, the HAR
  creator, the admin status `name`, the `Basic` realm, the MQTT client ids, and the contract report's `report`
  member (`apigenie-server-contract`) and JUnit suite name (`apigenie-server contract`). The reference page moved to
  [server](https://apigenie.pl/docs/reference/server); the old address redirects. The design is ADR-147.
- **One table of exit statuses for `apigenie`, `apigenie-generator` and `apigenie-server`.** 0 success, 1 findings
  (lint errors, breaking changes, `format --check` differences, `i18n apply --strict` unknown keys, `overlay
  --validate` problems), 2 a usage, input or unexpected error, 3 and 4 `apigenie-server`'s document and address
  errors, 5 a failed contract report (`apigenie-server`, `apigenie test`). The 1.0 compatibility promise freezes it.
  Scripts that check for the old numbers need these changes:
  - errors that exited with 255 (`-1`) now exit with 2: unreadable or invalid input files in `bundle`, `convert`,
    `changelog`, `diff`, `i18n`, `lint` and `overlay`, bad configurations, and every error of `apigenie-generator`;
  - errors that exited with 1 now exit with 2: unknown options and commands, missing files, configuration files that
    can't be parsed, `format` on a file with syntax errors or an unsupported document, `bundle` of a `.proto` file
    with errors, `license --library` with an unknown name, and unexpected errors in `apigenie-server` and `apigenie
    test`;
  - `apigenie test` exits with 2 instead of 3 when a request file, an environment file or the specification can't be
    read or parsed;
  - `apigenie` and `apigenie-generator` without a command, or with an unknown one, exit with 2 (255 before) and
    print the help of the command above it on the standard error.

  `apigenie-server` keeps 3, 4, 5 and 130. The design is ADR-141
  ([exit status](https://apigenie.pl/docs/reference/cli#exit-status)).
- **`--version` lists the binaries installed next to it.** `apigenie --version` prints the version on its first line,
  then `apigenie-generator VERSION` and `apigenie-server VERSION` for those found in the same directory (the same for
  the other two binaries). Scripts comparing the version should read the first line: `apigenie --version | head -n
  1`. The GitHub Action, the Homebrew formula and the release workflows do. Subcommands no longer have a `--version`
  of their own (`apigenie lint --version` printed 1.0).
- **`lint --formatter json` and `diff --report detailed --formatter json` write an object.** Lint JSON is
  `{ "formatVersion": 1, "results": [...] }` and the detailed diff report `{ "formatVersion": 1, "changes": [...] }`;
  both were bare arrays. Read `.results` and `.changes` instead
  ([compatibility](https://apigenie.pl/docs/reference/cli/compatibility)).
- **`diff` no longer rates deprecating as breaking.** In the `recommended` rules, setting or clearing `deprecated` on an
  operation, a parameter, a header or a schema is `non_breaking`: it announces a removal, and the removal is the
  breaking change (rated by `sunset_passed`, see Added). Gates that relied on it should set `operation.deprecated:
  breaking` (and `parameter`, `header`, `schema`) in `commands.diff.rules`. The design is ADR-172.
- **Seeded faker values change.** Faker now draws its values with algorithms of its own, the same on every platform, and
  `name`, `email` and other values of a `--seed` differ from 0.9.0's. Usernames and emails are ASCII (`Cieślar` becomes
  `Cieslar`), and `date.between` is a range (`{date.between: {from: 2024-01-01, to: 2024-12-31}}`) rather than an alias of
  `date.recent`.
- **Faker arguments are checked.** `x-faker`, `@mock(faker:, args:)`, `graphql.fields` and `fake()` reject arguments a
  provider doesn't take, of the wrong type or out of bounds (a negative length, a probability above 1) with faker's
  message, where they were clamped or ignored.
- **`apigenie format` keeps the format of OpenAPI, Swagger and AsyncAPI files without a configuration.** Formatting
  `api.json` with no `--config` used to write `api.yaml` next to it; JSON files now stay JSON. Set `format: yaml` to
  convert them.
- **The OpenAPI format configuration is checked.** Unknown keys (`indnet`), unknown objects in `property_order`,
  indents outside 2 to 9 and unknown output formats are reported with their line and column, and nothing is
  formatted; they used to be ignored or to abort the command.
- **The `recommended` OpenAPI preset changes more of a document.** It now reaches nested schemas, inline callbacks
  and the objects of OpenAPI 3.2, sorts the path templates of `paths` (its `paths: sorted` had no effect), orders
  more schema keywords (`$ref`, `$id`, `$defs`, `default`, `examples`, `readOnly`, `writeOnly`, `deprecated`...) and
  the fields of 3.2 objects, and orders Reference Objects by `reference`. Expect a one-time diff when reformatting
  with `extends: [recommended]`. `property_order.responses` applies to the status codes of operations; the names of
  `components.responses` follow the new `componentNames` key.

- **The configuration file is validated against a JSON Schema when it is loaded**, by `apigenie`,
  `apigenie-generator` and `apigenie-server`. Settings that were silently ignored are now errors (exit status 2) with
  the line, the column and the JSON pointer of the value: unknown keys under `commands.*` (the OpenAPI, AsyncAPI and
  Swagger linters, and the WebSocket generators, used to skip them), sections of commands that have no settings
  (`commands.bundle`, `commands.changelog`: `changelog` uses `commands.diff`), and values of the wrong type.
  `apigenie config check` lists the errors of a file; fix them, or remove the settings that did nothing. The design is
  ADR-145.
- **`apigenie` and `apigenie-generator` find the configuration file without `--config`**: `apigenie.yaml` (`.yml`,
  `.json`, or `.apigenie.*`) in the current directory or a parent up to the root of the git repository. Pass
  `--no-config` to run with the defaults, as before, in a repository that has such a file. `apigenie-server` falls
  back to the same file after its own `apigenie-server.yaml` and `apigenie-mock.yaml`.

- **The docs package is `@mykulyak/apigenie-docs`.** The npm project that `apigenie-generator docs` writes now
  depends on `@mykulyak/apigenie-docs` (`^0.1.0`), the new name of the web components package. 0.9.0 wrote
  `@mykulyak/apigenie-web-components` into `package.json`, and that package was never published under that name, so
  `npm install` failed. In a project generated by 0.9.0, replace that dependency with
  `"@mykulyak/apigenie-docs": "^0.1.0"`, or run `apigenie-generator docs` into it again.
- **`apigenie test` speaks MQTT 5.** MQTT regions connect with MQTT 5 (falling back to 3.1.1 when the broker refuses
  it), and the messages they publish are checked with their MQTT 5 properties against the AsyncAPI MQTT bindings. A
  region publishing to a channel whose binding states properties (a `payloadFormatIndicator`, `contentType`,
  `correlationData`, `responseTopic`, or an operation's `messageExpiryInterval`) fails with `message.properties.invalid`
  until it gives them with `# @property` lines, or keeps MQTT 3.1.1 with the `version: 3.1.1` setting. The design is
  ADR-110 (amended).

### Added

- **The OpenAPI format registry (https://spec.openapis.org/registry/format/) is API Genie's list of formats.**
  `apigenie-server` (mock and `--proxy-to`, OpenAPI and AsyncAPI), `apigenie test`'s contract checks and every other
  JSON Schema validation check the registry's formats beyond JSON Schema's:
  - int8, int16, uint8, uint16, uint32, uint64 and double-int ranges, with int64 and uint64 also as integer text;
  - decimal and decimal128, as numbers or text (decimal128: 34 significant digits, NaN, INF);
  - date-time-local and time-local (RFC 3339 without an offset);
  - http-date (IMF-fixdate and RFC 9110's obsolete forms) and unixtime;
  - ipv4-cidr and ipv6-cidr;
  - language (RFC 5646 tags);
  - media-range and char;
  - base64url and the RFC 8941 structured field items (sf-binary, sf-boolean, sf-decimal, sf-integer, sf-string,
    sf-token).

  commonmark, html, password and binary stay unchecked, as the registry allows. `openapi.custom_formats` in
  `apigenie.yaml` (or the server's configuration file) now reaches `apigenie-server`. Its formats are accepted as
  declared, and an entry naming a registry format replaces that format's type and turns its check off. The registry
  is vendored by `scripts/update-format-registry` (`--check` verifies the copy is current). The design is ADR-166.
- **Lint rules for formats: `schema-format-deprecated` and `schema-format-unknown`**, in the OpenAPI, AsyncAPI and
  Swagger linters.
  - `schema-format-deprecated` (a warning in every ruleset) reports `byte`, `binary` and `base64url`, which the format
    registry deprecates from OpenAPI 3.1, with what replaces them (`contentEncoding: base64`, `contentMediaType`,
    `contentEncoding: base64url`). In OpenAPI 3.0 and Swagger 2.0 documents, which have no replacement, the issues
    are hints.
  - `schema-format-unknown` (off in `recommended`, a warning in `strict` and `all`) reports a format that is neither in
    the registry nor in `openapi.custom_formats`, such as a misspelled `date_time`.
  - `apigenie lint` passes `openapi.custom_formats` to the format rules.
- **A `hint` severity for lint issues.** Hints are shown by every formatter (SARIF `note`, checkstyle and Visual Studio
  `info`, `hint` elsewhere, and `N hints` in the stylish summary), but never count as errors or warnings and never
  change the exit status. Rules can be configured with `hint` (or `info`) in `apigenie.yaml`.
- **The generators map the format registry's formats.**
  - Java, Spring and the AsyncAPI Java targets: `uint32`, `double-int`, `unixtime` and `sf-integer` become `Long`, and
    `uint64` becomes `BigInteger` in the OpenAPI targets. `date-time-local` and `time-local` become `LocalDateTime`
    and `LocalTime` in the AsyncAPI targets too.
  - C# and ASP.NET: `int8` to `uint64` become `sbyte`, `short`, `byte`, `ushort`, `uint` and `ulong`; `double-int`
    and `unixtime` become `long`, `decimal128` becomes `decimal`, and `date-time-local` becomes `DateTime`.
  - Go: `double-int`, `unixtime` and `sf-integer` become `int64`.
  - Python and FastAPI: numbers of format `decimal128` become `Decimal` like `decimal` ones, `date-time-local`
    becomes pydantic's `NaiveDatetime`, and `time-local` becomes `datetime.time`. Decimals of `type: string` stay
    strings in every generator but C#, keeping their `pattern`.
  - Elixir: `date-time-local` becomes `NaiveDateTime.t()`, and `time-local` becomes `Time.t()`.
  - TypeScript validators and Zod schemas check the ranges of `int8` to `uint64` and `double-int`. Zod validates
    `date-time-local` with `z.iso.datetime({ local: true })` and `time-local` with `z.iso.time()`.
  - `apigenie-generator data` and the server's generated values pass the checks of every registry format: integer
    widths keep to their range, `unixtime` is a time in 2020..2029, and `http-date`, the CIDRs, language tags, media
    ranges, the `sf-*` items, JSON pointers and regular expressions get values of their syntax.
- **The documentation components link formats to the format registry.** A schema's `format`, in `apg-schema`'s type
  label or its facts, links to the format's page of the registry (part `format-link`), and the generated examples
  have values for the registry's formats. The website's new Formats page lists every registry format with its JSON
  types and API Genie's support, and the lint rules, the configuration page and the server page link to it.
- **`apigenie-server --proxy-to kafka://host:port` contract-tests an AsyncAPI document's Kafka channels against a
  real cluster.** There is no broker in the server: it is a validating client of the cluster (ADR-170).
  - **Reading.** It reads the channels' topics (the Kafka binding's `topic`, else the address; parameters match the
    topic's segments) from the offsets they had at start, outside any consumer group, so the application's consumers
    and offsets are left alone.
  - **Checking.** Every record is checked as the application's (a channel with only `send` operations), a client's
    (only `receive` operations) or whichever matches. The value is checked against the messages, the headers against
    the message's `headers`, the key against the Kafka binding's `key` (new check `message.key.invalid`) and the
    partition against the channel binding's `partitions` (new check `message.partition.invalid`).
  - **Results.** Records are logged as `kafka-in` and `kafka-out` events and count in the coverage and the contract
    report like any other messages. Enforce mode reports, as records can't be stopped.
  - **Admin publishes.** `POST /__apigenie/asyncapi/publish` produces a Kafka channel's record to the cluster after
    the same checks, with the new `key`, `headers` and `partition` fields, and answers where it went.
  - **Connection.** `kafkas://` connects over TLS. SASL PLAIN credentials come from `APIGENIE_KAFKA_USERNAME` and
    `APIGENIE_KAFKA_PASSWORD`. The cluster needs Kafka 2.3 or later; compressed record batches are reported and
    skipped.
- **`apigenie-server --proxy-to amqp://host:port/vhost` contract-tests an AsyncAPI document's AMQP channels against a
  real AMQP 0-9-1 broker (ADR-171).** It is a client of the broker, not a broker.
  - **Reading.** It binds an exclusive queue of its own to the exchange of every channel whose address is a routing
    key (the address's parameters as `*` words of a topic exchange, any key of a fanout or headers exchange) and
    checks the messages it gets like the Kafka tap's records, plus their properties against the AMQP bindings
    (`deliveryMode`, `priority`, `expiration`, `userId`, `replyTo`, `timestamp`, `contentEncoding`, `messageType`;
    `message.properties.invalid`). Queue channels are left alone, as reading them would take the application's
    messages, and the tap says so.
  - **Results.** Messages are logged as `amqp-in` and `amqp-out` events and count in the coverage and the contract
    report.
  - **Admin publishes.** `POST /__apigenie/asyncapi/publish` publishes an AMQP channel's message to the broker, with
    the new `routingKey`, `properties` and `headers`, mandatory and confirmed (409 when no queue takes it).
  - **Connection.** `amqps://` connects over TLS. Credentials come from `APIGENIE_AMQP_USERNAME` and
    `APIGENIE_AMQP_PASSWORD`.
- **`AMQP` requests in `apigenie test`.** An `AMQP amqp://host:port/vhost` region publishes its body's messages to
  `exchange` and `routing-key` with `# @property` basic properties and headers, and reads `subscribe` queues and
  private queues bound with `bind: EXCHANGE KEY`; a message no queue takes is an error. The messages are checked like
  the tap's, and replies are paired by a correlation id in a header or a property (RabbitMQ's direct reply-to
  works). `--generate --amqp-url` makes one region per operation of an AMQP channel.
- **`KAFKA` requests in `apigenie test`.** A `KAFKA kafka://host:port` region produces its body's records to `topic`
  with a `key`, a `partition` and `# @property NAME VALUE` headers, and reads `subscribe` (or `topic`) until
  `# @expect` records came; the region's own records are left out.
  - A `topic` that a cluster creating topics on first use (`auto.create.topics.enable`) doesn't have yet is
    created by the region's first record and read from its start, also on Kafka 4, which reports such a topic
    unknown while it creates it.
  - With an AsyncAPI `--spec`, the records are checked like MQTT messages, plus their key and partition, and replies
    are paired with requests by a correlation id in a header or the payload.
  - Credentials come from `username` and `password`, else `APIGENIE_KAFKA_USERNAME` and `APIGENIE_KAFKA_PASSWORD`,
    and are redacted.
  - `kafkas://` uses `--ca-cert`, `--insecure` and `--client-cert`.
  - `--generate --kafka-url kafka://host:port` makes one region per operation of a Kafka channel.
- **`apigenie convert --from wsdl --to openapi31` imports SOAP services.** A WSDL 1.1 document with SOAP 1.1 or 1.2
  document/literal bindings over HTTP becomes an OpenAPI 3.1 document. The command also reads the WSDL documents
  and XML Schemas it imports and includes, as local files; remote ones aren't fetched. In the result:
  - Each SOAP operation is `POST {address path}/{operation}`, with `x-soap-address` and `x-soap-action`. The
    operations of a SOAP 1.1 and a SOAP 1.2 binding at one address merge, with a `text/xml` and an
    `application/soap+xml` body.
  - Requests and responses are SOAP envelopes whose schemas carry `xml` objects, so `apigenie-server` validates
    SOAP requests and answers SOAP envelopes. Faults are 500 responses, and one-way operations answer 202.
  - The XML Schema types (sequences, choices, attributes, simple content, restrictions and enumerations,
    extensions, occurrence bounds, nillable elements) are components, and the WSDL documentation is in the
    descriptions.
  - What has no counterpart is told as warnings with file, line and column: `xs:any`, substitution groups, lists,
    and decimals. WSDL 2.0, rpc/encoded and rpc/literal services are refused with exit status 2.

  The result lints without errors with `recommended`, and `diff` and the generators read it. `--from swagger2|wsdl`
  is optional: an XML input is WSDL. The library is `src/wsdl_convert`, tested on Apache CXF, NWS, ONVIF and WSDL
  1.1 Note documents vendored in `data/tests/wsdl` with their licences. The design is ADR-164.
- **`apigenie evolve plan OLD NEW` (experimental) plans safe API changes.** It splits the breaking changes between two
  OpenAPI 3.x documents into an expand wave (ship now: the old elements stay next to the new ones, `deprecated: true`
  with an `x-sunset` date) and a contract wave (ship after the window: the target document), writes `1-expand.yaml`,
  `2-contract.yaml` and `plan.yaml` to `--out` (default `evolve-out/`), and proves the plan with `diff` before writing
  anything: the expand wave is non-breaking against the old document, the contract wave has only scheduled removals
  (and what its units and the residue own) against the expand wave, and it equals the target. Ten recipes: removed
  operations and paths, moved paths (`--hints FILE` with `renames` as `METHOD /path` or diff's location syntax, a
  `window` and a `reason`), removed and renamed response properties, renamed request properties and parameters,
  removed request parameters, newly required request properties and parameters, removed request enum values
  (`x-deprecated-enum`); renames are detected when one member goes and one with the same schema comes. What no recipe
  makes safe is residue, listed with a reason (exit status 1). Each unit carries a server note (emit both, accept both,
  apply a default) and the report lists them as a checklist. `--window 90d|12w`, `--today DATE`, `--config` (the
  `commands.diff` block), `--format text|json` (`formatVersion: 1`,
  [apigenie-evolve-report.json](https://apigenie.pl/schemas/apigenie-evolve-report.json)). The reference page is
  [evolve](https://apigenie.pl/docs/reference/cli/evolve); the design is ADR-172.
- **`diff` knows sunset dates.** The rule condition `sunset_passed` holds when the removed element is deprecated and
  its `x-sunset` (an RFC 3339 date or date-time) is on or before the date of the comparison, `--today` (default: the
  current date; OpenAPI documents only). The `recommended` rules use it for `remove_item` of operations, path items
  (every operation sunset), parameters, component schemas and parameters, response properties and their `required`
  items, and request enum values listed in the schema's `x-deprecated-enum`: a removal after the sunset is
  non-breaking, before it breaking, and documents without `x-sunset` are rated as before. A property deprecated next
  to its `$ref` counts as deprecated.
- `apigenie-generator <target> --overlay FILE` applies OpenAPI Overlays (1.0 to 1.2) to the input before generating,
  in order, so the vendor extensions of a target can live in an overlay of their own instead of in the API
  description. Every target of OpenAPI and AsyncAPI documents takes it (AsyncAPI ones bundled first), and
  `commands.generate.<target>.overlay` lists overlays in the configuration file, relative to it, applied before the
  `--overlay` ones. An action whose target selects nothing is a warning with its position in the overlay, and an error
  with `--strict` (nothing is generated, exit status 2). Warnings and read errors about a value an overlay set point
  at the overlay's line (`spring.overlay.yaml:9:9 Warning ...`), and the document's own lines are kept, since
  `apigenie overlay` and every document built with `jv::JVBuilder` now keep the positions of what they copy. Each
  generator's reference page lists the `x-` extensions it reads. The codegen conformance suite generates its Spring
  target with `--overlay --strict` instead of a separate `apigenie overlay` step. The design is ADR-156.
- **Client certificates (mutual TLS) for `apigenie-server` and `apigenie test`.** `--client-cert FILE --client-key
  FILE` presents a certificate to the servers that ask for one: the `https://`, `wss://`, `mqtts://` and gRPC TLS
  upstreams of `apigenie-server --proxy-to` (also `tls.client_cert` and `tls.client_key` in the configuration,
  `APIGENIE_SERVER_CLIENT_CERT` and `APIGENIE_SERVER_CLIENT_KEY`), and every `https://`, `grpcs://`, `wss://` and
  `mqtts://` request of `apigenie test`, with `--insecure` too. `apigenie-server --tls-client-ca FILE`
  (`tls.client_ca`, `APIGENIE_SERVER_TLS_CLIENT_CA`) requires a client certificate issued by those authorities on
  every HTTPS, WSS, gRPC and MQTTS connection, the admin API included. A refused client is a warning in the log that
  says why. The subject of an accepted certificate is `clientSubject` in the JSON log and the admin API's log, and
  the contract report lists the clients (`clients` in JSON, a `client` property in JUnit, a `Clients:` summary
  line). A client certificate or key that can't be loaded, a lone `--client-cert` or `--client-key`, and
  `--tls-client-ca` without `--tls-cert` exit with status 2. A server that refuses the client's certificate now
  says so in the error (`the server requires a client certificate`) instead of "the connection closed before a
  response". Session resumption and revocation checks (CRL, OCSP) are not supported. The design is the amendment of
  ADR-104 ([server](https://apigenie.pl/docs/reference/server/tls#client-certificates-mtls),
  [test](https://apigenie.pl/docs/reference/cli/test)).
- **`apigenie-server --tls-cert` serves MQTT over TLS.** The MQTT broker of an AsyncAPI document uses the server's
  certificate (and `--tls-client-ca`), on port 8883 unless `--mqtt-port` or `asyncapi.mqtt_port` says otherwise;
  the startup line names it `mqtts://`. Before, it stayed cleartext on 1883.
- `apigenie-server` has a dashboard at `http://127.0.0.1:4010/__apigenie/ui` (the startup banner names it): Traffic as
  it happens, with an exchange's request, answer and validation problems, Copy as curl, Replay, Save as stub and Add to
  `.http`; Operations by tag with their hits and what answers them, and a fixed answer per operation (a status, an
  example, a generated body, a latency) saved as an override, with the `Prefer` header that does the same for one
  request; Scenarios with their rules and hits, a rule builder and the network simulation with the last response
  times; Contract with the gate against `--fail-on` and `--min-coverage`, the coverage, the violations by check, the
  operations never called and the report files; Data with the document store's collections, seeds and snapshots and
  `ctx.state`. Every panel copies its settings as configuration YAML or `x-apigenie-mock`. The page is built from
  the web components (`src/app_web`, the `apg-server-*` elements, `@mykulyak/apigenie-docs/server`) and embedded
  in the binary; it follows the admin API's rules (`--admin off`, `admin.allow_remote`, `admin.port`). The admin
  API says more for it: `/routes` items carry `tags`, `deprecated`, the declared `responses` with their
  examples and `lastSource`, `GET /overrides` answers whole rules and the scenarios list theirs as `ruleList`,
  the status gains `url`, `startedAt` and `logSize`. The design is ADR-167
  ([Dashboard](https://apigenie.pl/docs/reference/server/dashboard#dashboard)).
- The dashboard has a Channels screen for AsyncAPI documents, listed when a served document has channels: the
  channels by WebSocket, MQTT and HTTP with their operations, the clients connected and the messages counted; for a
  channel, its messages in and out as they happen, its clients, and Publish, a message sent as the application
  would (`POST /__apigenie/asyncapi/publish`) to every client of the channel or to one, with a payload started from
  the document's examples or left to the server; a payload the message's schema refuses shows the violations and
  goes nowhere, until Send anyway; Copy as curl. The admin API says more for it: `GET /__apigenie/asyncapi/channels`
  items carry `messageList`, each message with its `contentType`, `summary` and `examples` (payload and headers),
  and `POST /__apigenie/asyncapi/publish` takes `client`, an id of `/asyncapi/clients`, to send to that one client
  (404 `asyncapi-unknown-client` when it isn't connected). The design is the amendment of ADR-167
  ([Dashboard](https://apigenie.pl/docs/reference/server/dashboard#dashboard)); gRPC and GraphQL variants of the
  dashboard come after 1.0.
- `apigenie-server`'s admin API serves what a dashboard needs. `GET /__apigenie/events` streams the log as it happens,
  as Server-Sent Events: the entry's id as `id:`, its kind as `event:` (`request`, `ws-out`, `reload`, and the new
  `scenario` and `contract-updated`), a `violation` event after an entry with violations, `?type=`, `?level=`,
  `?service=`, and `?after=` or `Last-Event-ID` to replay what the log still holds. While a stream is open every
  exchange's request and response headers and bodies are captured; entries gain `responseHeaders`, Base64 bodies for
  bytes that aren't UTF-8, and `*BodyTruncated`, and `log.body_limit` now bounds what the log keeps and what `/log`
  returns. `/routes` and `/scenarios` count `hits` with `lastStatus` and `lastAt` (`DELETE /__apigenie/hits` starts
  over). `POST /__apigenie/stubs {"id": 42}` makes a stub file of a logged exchange, written to `dir` or
  `proxy.record_dir`, or answered. `GET /__apigenie/contract.json` and `/contract.xml` download the report as
  `--report` and `--report-junit` would write it. For AsyncAPI documents, `GET /__apigenie/asyncapi/channels` and
  `/asyncapi/clients` list the channels and the WebSocket and MQTT clients, and `POST /__apigenie/asyncapi/publish`
  sends a message (given, or made as the schedule would) to a channel's clients, answering 422 when it doesn't match.
  A server of several services names the service of every item and event. The design is ADR-161
  ([Admin API](https://apigenie.pl/docs/reference/server/dashboard#admin-api)).
- `apigenie-server` serves several services at once, on one port with a prefix per service: several `SPEC`s
  (`apigenie-server pets.yaml orders.yaml events.yaml` mounts `/pets`, `/orders` and `/events`) or the configuration's
  `services` list, each with `name`, `spec`, `mount` (a path prefix, default `/<name>`; `{host: ...}`; `{port: ...}`,
  which a `.proto` file's service needs) and its own `proxy`, `stubs`, `scenarios`, `validation`, `security`,
  `operations` and other document settings over the server's. AsyncAPI WebSocket channels share the port; the MQTT
  broker is one per server, and services whose MQTT channels collide have their topics served under `<name>/`. Every
  event, admin API item (`/routes`, `/scenarios`, `/overrides`, `/log`, the status's documents), HAR entry and report
  section names its service; `GET /__apigenie/services` lists them and `?service=NAME` narrows any admin endpoint. The
  contract report has a section per service and a combined summary, to which `--fail-on` and `--min-coverage` apply.
  The startup line lists the services and their URLs. One `SPEC` is served as before. The design is ADR-159.
- `apigenie-generator server mcp` (experimental) generates a Model Context Protocol server in TypeScript from an
  OpenAPI 3.x document, on the official MCP SDK (`@modelcontextprotocol/server` 2), so that AI agents call the API
  through typed tools: one tool per operation, named after its `operationId`, described by its summary and
  description, with a Zod input schema of its parameters and body. The tools call the API through a generated fetch
  client (`src/client`) and return the status and body of the response as structured content, with an output schema;
  failed requests and responses the document doesn't describe are error results that keep the body. Binary bodies and
  multipart files are base64 strings. `include_tags`, `exclude_tags` and `x-mcp: false` select the operations; the
  base URL and the credentials of the security schemes come from environment variables (`<PREFIX>_BASE_URL`,
  `<PREFIX>_API_KEY`...). `--mock` adds `npm run mock`, serving the document with `apigenie-server`, and makes it the
  default base URL for demos. Configured under `commands.generate.server_mcp`; the design is ADR-158. The codegen
  conformance suite checks it at Levels 1 to 3, Level 3 driving the tools with an MCP client against
  `apigenie-server --proxy-to`. The fetch client generator exposes how its functions call the operations
  (`client_fetch::Plugin::bindings()`), and the operation selection of the Elixir and Go generators moved to
  `openapi_generator`.
- `apigenie-generator client elixir` also takes AsyncAPI 3.x documents and generates an Elixir library for the
  counterpart of the described application (or, with `perspective: application`, the application's Kafka library).
  Its WebSocket channels connect on Mint.WebSocket, with the Phoenix Channels protocol of `server phoenix` (topics
  joined on `/socket/websocket`, replies to refs, heartbeats) or with the plain frames of the document at the
  channels' addresses: `connect` takes the address parameters and the ws binding's query, `send_*` sends, a request
  function waits for its reply (matched by correlation id on plain connections), and what the server sends is
  decoded and given to the callbacks of a behaviour. Its Kafka channels have `send_*` and `request_*` functions on
  brod and a consumer group (`:brod_group_subscriber_v2`) per received operation, sharing the dispatch, decoding and
  replies of `server phoenix`'s pipelines; the library depends on `snappyer`, so that brod reads Snappy-compressed
  records. Configured under `commands.generate.client_elixir.asyncapi`; the design is
  ADR-154. The codegen conformance suite checks both perspectives at Levels 1 and 2 (with `mix dialyzer`) and, at
  Level 3, runs it against `server phoenix`: the WebSocket channels in both framings, the plain one through
  `apigenie-server --proxy-to ws://…`, and the Kafka channels both ways on the broker of the workflow's service
  container.
- `apigenie-generator server phoenix` also takes AsyncAPI 3.x documents and generates a Phoenix application of their
  WebSocket and Kafka channels. Each WebSocket channel is a Phoenix channel (its address as the topic,
  `/tracking/{shipmentId}` as `tracking:<shipmentId>`, joined on `/socket/websocket`) and also a plain WebSocket at
  its address, whose frames are the messages of the document; both decode the address parameters, the ws binding's
  query and the received messages into model structs before a behaviour's callbacks get them, and the channel
  module's `push_*` and `broadcast_*` functions send. A request's callback returns its reply, which gets the request's
  correlation id. Each received Kafka operation is a Broadway pipeline (broadway_kafka) dispatching records by
  `ce_type`, payload property or decoding to the callbacks of its behaviour, with `on_unknown` and `on_invalid`
  hooks (a replier's `:ok` sends no reply) and batching from `x-apigenie-broadway` of the Kafka binding or the configuration; each sent operation has
  `send_*` functions on brod, and requests wait for their replies by correlation id on the reply topic; the project
  depends on `snappyer`, so that brod reads Snappy-compressed records. MQTT, AMQP
  and HTTP channels are skipped with an info line, Avro payloads with a warning. Configured under
  `commands.generate.server_phoenix.asyncapi` (`perspective: counterpart` generates the Kafka counterpart); the
  design is ADR-154. The codegen conformance suite checks both perspectives at Levels 1 and 2 (`mix compile
  --warnings-as-errors`, `mix format --check-formatted`, `mix credo --strict`) and, at Level 3, the plain
  WebSockets through `apigenie-server --proxy-to ws://…` and the application against its counterpart on the Kafka
  broker of the workflow's service container.
- `apigenie-generator server absinthe` generates an Absinthe server of a GraphQL schema: a Mix project on Absinthe
  1.12, Absinthe.Plug, Plug and Bandit. Its schema module imports the SDL shipped with the project (`import_sdl`,
  descriptions, deprecations, defaults and `@oneOf` included), and `hydrate/2` attaches:
  - resolvers: a behaviour per object type with a callback per root field and per field with arguments, calling
    the implementation configured for it (`config :app, App.Resolvers.Query, impl: MyApp.Query`), an error
    without one;
  - the resolution of interfaces and unions (`__typename` or an implementation);
  - parse and serialize stubs of the custom scalars.

  Custom directives are declared in a prototype schema. An optional Dataloader source is added with `dataloader`,
  and the router serves the endpoint and, in dev, GraphiQL. Subscriptions get resolvers but no transport.
  Configured under `commands.generate.server_absinthe`; the design is ADR-152. The codegen conformance suite checks
  it at Levels 1 to 3 (`mix compile --warnings-as-errors`, `mix format --check-formatted`, `mix credo --strict`,
  and the application answering `apigenie test` and the fixture's dataset with the data of `apigenie-server`).
- The foundation of GraphQL code generation (ADR-151): `graphql_generator` reads a GraphQL schema into a
  target-neutral model (types with their extensions merged, fields, arguments, enum values, input types, scalars,
  directives, descriptions, deprecations and default values) for the GraphQL targets of `apigenie-generator`, and
  the codegen conformance suite gains a GraphQL fixture: the Carpet Express GraphQL API
  (`data/fixtures/graphql/carpet-express.graphql`), the GraphQL face of the OpenAPI and AsyncAPI fixtures, with its
  feature catalog, field coordinates (`Query.shipment`) as probe identifiers, and a dataset of operations whose
  answers from `apigenie-server` back the Level 3 of GraphQL servers.
- `apigenie-generator server elixir-grpc` generates an Elixir gRPC server of a `.proto` file set on elixir-grpc
  (`grpc_server` 1.0) and protobuf-elixir 0.17: the modules of the messages, enums and services as
  protoc-gen-elixir writes them (no protoc needed), a behaviour per service with a callback per method (client and
  server streams as Elixir enumerables), a `GRPC.Server` calling the implementation configured with `config :app,
  <Service>, impl: ...` (UNIMPLEMENTED without one), the endpoint and the application (`mix run --no-halt`, port
  50051 or `PORT`). `apigenie-generator client elixir` given a `.proto` file generates a gRPC client on `grpc` 1.0
  and Mint: the same modules with the stubs, and a module per service with a typed function per method returning
  `{:ok, response}` or `{:error, %GRPC.RPCError{}}`, deadlines and metadata as options. Configured under
  `commands.generate.server_elixir_grpc` and `commands.generate.client_elixir.protobuf`; the design is ADR-153. The
  codegen conformance suite checks both at Levels 1 to 3 (`mix compile --warnings-as-errors`, `mix format
  --check-formatted`, `mix credo --strict`, `mix dialyzer`; the server under `apigenie test`, the client calling
  all 24 methods through `apigenie-server`).
- Protobuf code generation starts: the `protobuf_generator` library gives the Protobuf targets of
  `apigenie-generator` a model of a `.proto` file set (the file and its imports, found with `-I/--proto-path` and
  among the embedded `google/protobuf`, `google/api` and `google/rpc` files) on the resolved descriptors of the
  Protobuf runtime: messages with their nesting, fields with their cardinality, oneofs, maps, enums, services and
  the streaming kind of their methods, comments, deprecations and `(google.api.field_behavior)`. Proto3 only. The
  codegen conformance suite has a Protobuf fixture, the gRPC services of Carpet Express
  (`data/fixtures/protobuf`: 7 services, 24 methods of all four streaming kinds, a catalog of 42 features), and
  runs Protobuf servers under the gRPC contract tester and clients through `apigenie-server` as a validating gRPC
  proxy. The design is ADR-150; Connect-ES and connect-go are the next targets.
- The [Compatibility](https://apigenie.pl/docs/reference/cli/compatibility) page states the 1.0 promise: what semantic
  versioning covers from 1.0.0 (commands, options, configuration keys, environment variables, exit statuses, JSON
  report versions, the docs bundle, the `apigenie-server` admin API, the `x-apigenie-*` extensions), what it doesn't,
  and how a removal is deprecated first. The `--help` of `apigenie`, `apigenie-generator` and `apigenie-server` links
  to it. The design is ADR-155.
- **`apigenie-catalog`, a fourth binary (experimental), keeps the API catalog of a repository.** Every archive, the
  `.deb` and `.rpm`, the npm package and Homebrew install it next to `apigenie`, `apigenie-generator` and
  `apigenie-server`; `--version` and `--help` of each binary name it, and `apigenie catalog ...` prints the
  `apigenie-catalog` command to run instead ([catalog](https://apigenie.pl/docs/reference/catalog)). The
  design is ADR-160.
- `apigenie-catalog list [DIR]` lists the API specifications of a repository with no configuration: every OpenAPI,
  AsyncAPI and Swagger document, Protobuf file and GraphQL schema that git tracks or doesn't ignore (every file
  outside git), less `catalog.exclude`, with its name (from the catalog section, `info.title`, the Protobuf package
  or the file name), format and version, owner, path and the commit that last changed it. `--json` writes a report
  with `formatVersion` and a published schema,
  [apigenie-catalog-report.json](https://apigenie.pl/schemas/apigenie-catalog-report.json).
- `apigenie-catalog init [DIR]` writes a `catalog` section to `apigenie.yaml` (created at the root of the repository
  when there is none) with one entry per specification: name, path and an `owner: null` placeholder. Running it
  again adds new specifications, keeps edited entries and their comments, and reports the entries whose files are
  gone (`--prune` removes them); `--dry-run` prints the file. Only the section's lines change in an existing YAML
  file.
- The `catalog` section of the configuration file (`specs` with `path`, `name` and `owner`; `exclude`) is part of
  the configuration schema, so `config check`, `config --for catalog` and editors know it
  ([configuration](https://apigenie.pl/docs/reference/cli/configuration#catalog)).
- `apigenie-server` keeps documents in a store that scripts share (see
  [Document store](https://apigenie.pl/docs/reference/server/store)). Scripts get `ctx.db.<collection>`
  with `insert`, `get`, `find(where, {limit, offset, sort})`, `count`, `all`, `update` (a JSON merge patch), `replace`,
  `delete` and `clear`; `where` takes equality and `$eq`, `$ne`, `$in`, `$gt`, `$gte`, `$lt`, `$lte` and `$contains` on
  fields and paths (`address.city`), and documents get the next id unless they bring one. `ctx.state` is unchanged.
  With `db.crud: auto` (or `--crud`), an OpenAPI document's `/shipments` and `/shipments/{id}` are served from the
  store without a script: `POST` stores the body (its `readOnly` properties generated, the document checked against
  its schema), `GET` lists with the operation's own paging, filter and `sort` parameters (envelopes get `total` and
  friends), `PUT`, `PATCH` (a merge patch) and `DELETE` change it, and an unknown id is 404; `x-apigenie-mock:
  {resource: ...}` names a resource (always served), binds it to a schema or switches it off. Writes that don't match
  the schema are reported, or refused with `--strict`. Collections are seeded from the files of `db.seed`, else the
  list operation's example, else `db.generate` documents generated with the run's seed, and `ctx.db.reset()` or `POST
  /__apigenie/db/reset` puts them back. A request's `X-Apigenie-Test` header gives each test run a namespace of its own that starts from the seeds.
  The admin API shows the store (`GET /__apigenie/db`, `/db/{name}`), replaces or clears a collection, and takes and
  restores named snapshots (`PUT /__apigenie/db/snapshots/{name}`, `POST .../restore`). `--db-file` (`db.file`, env
  `APIGENIE_SERVER_DB_FILE`) keeps the store in a JSON file across runs, written when the server stops or on `POST
  /__apigenie/db/save`; writes are `db` events in the log. With several services, each has a store of its own (and
  `--db-file` is refused). Configured under `commands.mock.db`; the design is ADR-157.
- `apigenie-generator server phoenix` generates a Phoenix 1.7 application of an OpenAPI 3.x document, on Bandit and
  Jason, without Ecto, HTML or OpenApiSpex: a router with a route per operation (static segments first, `QUERY` and
  `COPY` through `match`, segments with several parameters split by the runtime), a behaviour per tag whose callbacks
  receive the decoded parameters and body, and a controller per tag calling the configured implementation (501
  without one). Requests are checked before they reach it: missing credentials give 401, parameters and bodies that
  don't match their schemas 400, other media types 415, all as problem documents; credentials go to an optional
  authenticator. `mix phx.server` serves it. Configured under `commands.generate.server_phoenix`; the design is
  ADR-131. The codegen conformance suite checks it at Levels 1 to 3 (`mix compile --warnings-as-errors`, `mix format
  --check-formatted`, `mix credo --strict`, and `apigenie test` against `mix phx.server`).
- `apigenie-generator client elixir` generates an Elixir client of an OpenAPI 3.x document on Req and Jason: a Mix
  project with a module per tag and a function per operation, `op(client, [body,] params \\ [], opts \\ [])`,
  returning `{:ok, body}` (the response decoded into its model, a list of them, text, bytes or `nil`) or
  `{:error, %ApiError{}}`, and a `!` variant raising the error. Parameters are a keyword list encoded in their
  styles (`deepObject`, delimited arrays, `content` parameters as JSON), bodies are model structs or maps sent as
  JSON, forms or multipart parts (files, lists of files), and `new/1` takes the base URL, Req options for retries
  and timeouts, and credentials for every security scheme: API keys in headers, the query or cookies, HTTP bearer
  and basic, OAuth2 and OpenID tokens, or a supplier called before each request. Configured under
  `commands.generate.client_elixir`; the design is ADR-131. The codegen conformance suite checks it at Levels 1 to 3
  (`mix compile --warnings-as-errors`, `mix format --check-formatted`, `mix credo --strict`, `mix dialyzer`, and
  every operation called through `apigenie-server --proxy-to`).
- Elixir models for the coming Elixir targets (`client elixir`, `server phoenix`): one module per schema
  with a struct, `@type t` and `new/1`, `new!/1` and `to_map/1` decoding and encoding JSON maps; string enums
  as atoms, `oneOf`/`anyOf` with a discriminator dispatching on the tag, `allOf` flattened, dates, times and
  base64 decoded, `additionalProperties` as a map field. The code passes `mix format --check-formatted` and
  `mix compile --warnings-as-errors`, which `WITH_ELIXIR_TESTS` checks (`ctest -L elixir`); the design is
  ADR-131.
- `apigenie i18n check` compares a translation file with the texts of a spec, Protobuf or GraphQL file (or an
  `i18n extract` output) and fails unless every text is translated and every key is a text; it reports missing, empty,
  unknown and invalid keys and the coverage, as text or JSON (`--format json`, `--allow-empty`)
  ([i18n](https://apigenie.pl/docs/reference/cli/i18n)).
- `apigenie i18n sync` updates a translation file after the document changed: it keeps the translations of unchanged
  texts and reports the new texts, the changed ones whose translations may be stale (`--drop-changed` drops them) and
  the removed ones (`--prune` drops them).
- `i18n extract` extracts more OpenAPI texts: the `summary` and `description` of Reference Objects (3.1+), keyed at
  the `$ref`, the `summary` of tags and `name` of servers (3.2), the descriptions of OAuth scopes, and the titles and
  descriptions of schemas under `$defs`, `dependentSchemas` and `additionalItems`.
- The `openapi_i18n` WebAssembly module applies translations (`apply`), compares and updates translation catalogs
  (`compare`, `sync`), and its `Translator` lists, replaces and removes locales and falls back on other locales
  (`translateWithFallback`).
- `apigenie generate ...` exits with 2 and prints the command to run instead: `code generation moved to
  apigenie-generator; run: apigenie-generator <the same arguments>`. `apigenie mock ...` points to `apigenie-server`
  the same way.
- The `--help` of each binary ends with the exit statuses and a line naming the other two binaries and what they do.
- Experimental commands, outside the 1.0 compatibility promise, say so in their `--help` and on the first line they
  print (on the standard error, so that their output stays usable): `apigenie convert` (one target) and
  `apigenie-generator schema zod` (no conformance Level 3 yet). Their reference pages and the CLI overview carry the
  same label; `docs/experimental.md` lists what is experimental and why.
- Every JSON report has a top-level `formatVersion` (1): lint, diff (`status`, `changelog`, `detailed`), changelog,
  the `apigenie test` report and the summary line of `apigenie test --formatter json`, the contract report of
  `apigenie-server`, and the docs bundle manifest (next to `apigenieDocs`). Adding fields keeps the version; removing
  or changing one bumps it (ADR-140).
- JSON Schemas of these formats, published at `https://apigenie.pl/schemas/` (`apigenie-lint-report.json`,
  `apigenie-diff-report.json`, `apigenie-changelog-report.json`, `apigenie-test-report.json`,
  `apigenie-contract-report.json`, `apigenie-docs-manifest.json`) and linked from each command's reference page, and
  a Compatibility page listing the versioned outputs.
- XML request and response bodies (`application/xml`, `text/xml`, `+xml`) are checked by `apigenie-server`, its validating
  proxy and `apigenie test`: a body is parsed, mapped to the JSON value its schema's `xml` objects describe (`name`,
  `namespace`, `prefix`, `attribute`, `wrapped`, OpenAPI 3.2 `nodeType`) and validated like a JSON body. A body that
  isn't well-formed is `request.body.malformed` (400) or `response.body.malformed` with its line and column; a root
  element other than the schema's is reported too. The mock answers XML media types with XML, and `apigenie test
  --generate` sends XML bodies, written the same way
  ([XML bodies](https://apigenie.pl/docs/reference/server/validation#xml-bodies)). The design is ADR-130.
- **`apigenie test` streams.** GraphQL subscriptions go over WebSocket with the graphql-ws protocol
  (`graphql-transport-ws`) instead of a single `POST`. The request's headers go on the handshake and in
  `connection_init`. The events are the response (`?? body $[0].data...`, `response.messages`), and each is checked
  against the operation's selection set at `next[i]`. `# @expect` and `# @timeout` end the subscription, and
  `--generate` adds a request per `Subscription` field.

  gRPC client- and bidi-streaming methods are no longer skipped. Their messages are written as for WS regions, with
  `===` between them and `=== wait-for-server` to wait for an answer. Each message is checked against the `.proto`
  file at `message[i]`, and a bidi call's body is the array of its answers. `--generate` sends two messages to each
  stream.

  Both count in the coverage. The design is ADR-109 and ADR-111 (amended 2026-10-12)
  ([GraphQL subscriptions](https://apigenie.pl/docs/reference/cli/test/graphql#subscriptions),
  [gRPC requests](https://apigenie.pl/docs/reference/cli/test/grpc)).
- The OpenAPI model reads 3.2's `xml.nodeType` (`x-nodeType` in 3.0 and 3.1 documents) and writes it back.
- Internal: the `xml` library, a strict XML 1.0 + Namespaces 1.0 parser (a pull reader and an immutable tape DOM like
  jv's, positions on every node) and a streaming writer with `escapeText`/`escapeAttribute`. DTDs and entities other
  than the five predefined ones are refused, so external entities and entity expansion ("billion laughs") are errors;
  depth, attribute count and input size are limited. The design is ADR-129.
- Colored output in Windows consoles: the CLI, `apigenie-generator` and `apigenie-server` style their output when it
  goes to a console, as they do in terminals elsewhere, and still not when it is redirected or `NO_COLOR` is set.
- `lint --watch` prints the files whose change triggered the run (on standard error, so that the report stays
  parseable), and no longer misses edits made while a run is in progress.
- **Faker providers take typed and named arguments and describe themselves.** `x-faker` accepts `{"string.alpha":
  {length: 6, casing: upper}}` and `{provider, args, options}`, the GraphQL mock's `args` and `graphql.fields` take a list
  or an object, and mock scripts call `fake('internet.email', {provider: 'example.org'})`. 295 providers (from 215)
  cover a person's sex and country, an email's names and host, phone formats, string casing, address countries, date
  formats and more ([faker reference](https://apigenie.pl/docs/reference/cli/faker)).
- **Faker records**: `person.profile`, `location.address`, `finance.card`, `finance.currency` and `commerce.product`
  make related values together (one sex for a person's names, a username and email of those names, one country for an
  address with its time zone, one issuer for a card), written as objects in mocked responses and generated data.
- `helpers.fromPattern` (alias `helpers.fromRegExp`) and `helpers.replaceSymbols`, and `date.between`,
  `date.birthdateByYear` and `date`/`time` formats for dates.
- **OpenAPI formatting at every depth.** The formatter recognizes the objects of OpenAPI 3.0, 3.1 and 3.2 by walking
  the document from its root: schemas under `properties`, `items`, `allOf`, `$defs`, `if`/`then`/`else` and every
  other applicator, path items and operations of callbacks at any depth, 3.2 `query` operations,
  `additionalOperations`, `itemSchema`, `prefixEncoding` and `itemEncoding`, the content and examples of headers,
  and individual OAuth flows (`oauthFlow`). Example payloads and extension values are never taken for OpenAPI
  objects. The design is ADR-149.
- **Independent orders for named maps and raw values**: `componentNames`, `webhooks`, `callbacks`, `callback`,
  `content`, `headers`, `properties`, `scopes`, `extension` and `exampleValue`, so that, for example, component
  schemas can be sorted by name while the properties of each schema keep their order.
- **Layout options for OpenAPI**: `line_width`, `newline` (`lf`, `crlf`), `final_newline` and `document_marker`,
  backed by new jv write options.
- **`style_overrides`** give chosen fields their own YAML styles, by field name and object kind, such as literal
  descriptions or flow `required` lists.
- **`apigenie format --openapi-fragment KIND`** formats files holding a single OpenAPI object (a schema, a path
  item, a response...) with the rules of that object.
- **A typed options API** (`openapi_format::FormatOptions`, `Formatter::setOptions`) for C++ consumers of the
  formatter library, validated like the configuration file.

- `apigenie config` prints the effective configuration (YAML, or JSON with `--json`): the values of the file, those
  set by `APIGENIE_SERVER_*` environment variables (or their `APIGENIE_MOCK_*` fallbacks), and the defaults of the
  settings the file leaves out. `--origin` annotates each value with the file, the variable or `default` that set it,
  and `--for <section>` limits it to one section (`lint`, `format`, `diff`, `generate`, `generate.<target>`, `mock`)
  ([config](https://apigenie.pl/docs/reference/cli/config)).
- `apigenie config check [FILE]` validates a configuration file and exits with 2 on errors, reporting every unknown
  setting at once with a suggestion for a misspelled name, and the allowed values of a setting with a fixed set.
- `apigenie config schema [--for <section>] [--standalone-server] [--out FILE]` prints the JSON Schema (draft-7) of
  the configuration file, of one section, or of a standalone `apigenie-server.yaml`. Each release publishes them at
  `https://apigenie.pl/schemas/apigenie-config/<version>.json` and `.../apigenie-server-config/<version>.json`, with
  `latest.json`, for `# yaml-language-server: $schema=...` comments in editors.
- `--no-config` for `lint`, `format`, `diff`, `changelog` and every `apigenie-generator` target.
- MQTT 5 message properties end to end. `apigenie-server --proxy-to mqtt://` relays user properties, payload format
  indicator, content type, response topic, correlation data and message expiry both ways and checks them against the
  AsyncAPI MQTT bindings (0.2.0): the new contract check `message.properties.invalid` (error) for a payload format,
  content type, correlation data or response topic other than the message binding says, and a missing or longer
  message expiry than the operation binding's; the user properties are checked as the message's `headers`
  (`message.headers.invalid`); a reply's header correlation id and Correlation Data are compared with the request's.
  The mock's own broker sends the properties its bindings and headers state, checks its MQTT 5 clients' and answers
  requests on their reply address or Response Topic. `apigenie test` connects with MQTT 5 (`version: 5`, `3.1.1` or
  `auto`), sets properties with `# @property content-type ...`, `response-topic`, `correlation-data`,
  `payload-format-indicator`, `message-expiry-interval` and `user NAME VALUE`, subscribes to its response topic, pairs
  replies by reply-address user property or Response Topic, and `--generate` writes the properties of the bindings.
  Reports count the messages whose properties were checked (`summary.properties`). The design is ADR-112 and ADR-110
  (amended); see [test](https://apigenie.pl/docs/reference/cli/test) and
  [server](https://apigenie.pl/docs/reference/server).

- `apigenie-server --record DIR` records the session: every exchange the server answered, of every service and every
  protocol (HTTP, GraphQL operations, gRPC calls with their streams, WebSocket and MQTT messages of both sides), in
  the order it happened, each as a file under `DIR/<service>/` numbered across the session, with `session.yaml` naming
  the services (with the SHA-256 of their documents) and listing the exchanges. Each exchange carries `sequence`,
  `service` and `test`, the test being the request's `X-Apigenie-Test` header, a gRPC call's `x-apigenie-test`
  metadata, or the mark set with `POST /__apigenie/record/mark {"test": ...}`. HTTP and gRPC exchanges keep the stub
  forms of `--record-dir`, so `--stubs DIR/<service>` still loads them; GraphQL operations the example form; messages a
  form of their own. `POST /__apigenie/record/start` and `/stop` record a part of a run, `GET /__apigenie/record` says
  whether one is on, and the dashboard's Traffic screen has Record session and Save session. `--record-redact` (and
  `record.redact`) hides more headers and, by JSON pointer, values of bodies and messages. `apigenie-server session
  export DIR --har FILE` writes a session's HTTP exchanges, GraphQL operations and gRPC calls as HAR 1.2, in order,
  with the test of each entry. `--record-dir` and `--record-har` are unchanged. The design is ADR-168
  ([Session recording](https://apigenie.pl/docs/reference/server/recording#session-recording)).

- `apigenie-server --replay DIR` replays a recorded session for a test suite, without the real servers: each request
  gets the next unused recorded exchange of its test that matches it, so the same request twice in a test gets the
  first recorded answer, then the second. The test is the `X-Apigenie-Test` header (`x-apigenie-test` metadata for
  gRPC); untagged requests share one test drawing from the whole session; `POST /__apigenie/replay/reset {"test": ...}`
  restarts a test's counters. Matching leaves out dates, the `readOnly` fields of OpenAPI request bodies, volatile
  headers and what `--replay-ignore HEADER|/POINTER` names. `--replay-missing` says what a request none matches gets:
  `fail` (a 502 problem naming the closest recording and the differences, the default), `generate` (the mock's answer)
  or `passthrough` (`--proxy-to`'s, and with `--replay-update` the run replaces the session). Every protocol replays:
  HTTP, GraphQL operations and subscriptions, AsyncAPI WebSocket, MQTT and HTTP channels (the recorded messages as the
  server's side, in order) and gRPC calls, bidirectional streams in their recorded interleaving. When the server stops
  it reports the exchanges never replayed and the requests that matched none, and exits with status 5 if there are
  any; `GET /__apigenie/replay` gives the report at any time, and `replay:` configures it all. The reference page has a
  Playwright example. The design is ADR-169
  ([Session replay](https://apigenie.pl/docs/reference/server/recording#session-replay)).

### Changed

- `apigenie` and `apigenie-server` are about 360 KB smaller: Mbed TLS is built with only what their TLS uses (TLS 1.2
  and 1.3 with certificates, AES-GCM and ChaCha20-Poly1305, x25519 and the NIST P-256, P-384 and P-521 curves). HTTPS,
  WSS, gRPC and MQTTS servers that offer only static RSA or DHE key exchange, or only other ciphers, can no longer be
  reached by `--proxy-to` or `apigenie test`; the handshake fails with a fatal alert. ADR-104.
- **`schema-format-type-mismatch` and `schema-format-defined` follow the OpenAPI format registry**, in the OpenAPI,
  AsyncAPI and Swagger linters, and accept the formats of `openapi.custom_formats`. `schema-format-type-mismatch` used
  to check a fixed list of formats; it now checks every registry format (`int8` on a string, `date-time-local` on an
  integer, ...), so existing specifications can get new errors. Its messages say which values the format is for
  (`Schema type and format do not match: "int8" is a format of number values`). Some pairs it used to report are
  accepted now, as the registry allows them: `int64` and `uint64` on strings, `decimal` on strings and numbers, an
  integer format on `type: number`. `schema-format-defined` accepts the registry's integer formats (and `unixtime`) for
  integers and its number formats (`decimal`, ...) for numbers. The Swagger linter keeps to the formats Swagger 2.0
  defines.
- Declarative lint rules with `severity: info`, `hint`, `2` or `3` report hints instead of warnings.
- `apigenie-generator server orpc` meets the codegen conformance bar of the other servers: Level 1 runs on OpenAPI 3.0,
  3.1 and 3.2, and Levels 2 (tsc, ESLint) and 3 (`apigenie test` against the generated server) are wired, with only
  QUERY and COPY, which oRPC doesn't route, expected to fail; it is no longer listed as not settled in
  `docs/experimental.md`. The generated server now reads what oRPC doesn't decode by itself: cookie parameters,
  `content: application/json` parameters, a path segment of several parameters (`/labels/{labelId}.{extension}`),
  JSON media types other than `application/json` and JSON Lines bodies (parsed by the server), form fields converted
  to their types, and file uploads; bodies and responses take every media type of the operation, with binary responses
  as `Blob`s and `text/event-stream` as an `eventIterator()` of the `itemSchema`. A discriminator's `defaultMapping`
  selects the default option, operations with servers of their own are also served at their paths, `4XX`/`5XX` ranges
  and `default` responses become errors, `writeOnly` properties are left out of responses, and the handler stubs and
  `server.ts` pass typescript-eslint's recommended rules (regenerate `server.ts` and the handlers, which are written
  once, to get them).
- The Zod schemas of `generate schema zod`, `server mcp` and `server orpc` check `unevaluatedProperties: false` against
  the properties the schema and its `$ref`, `allOf` and conditional schemas declare, instead of ignoring it with a
  warning: closed allOf subtypes such as Person or ParcelShipment reject unknown properties.
- `apigenie-server`'s status (`GET /__apigenie`) counts the clients' requests only: the admin API's and the
  dashboard's own exchanges and CORS preflights are no longer in `requests` (ADR-167).
- XML bodies of `apigenie-server`, its validating proxy and `apigenie test` (ADR-130) changed in three ways, found
  serving SOAP envelopes (ADR-164):
  - Child elements are written in the order the schema declares its properties, as XML Schema sequences require.
    Before, generated values put required properties first.
  - An element with the local name of a property but in another namespace than the property's `xml.namespace` is
    no longer taken for it. It is kept as `{namespace}name`, so `additionalProperties: false` reports it and the
    property counts as missing.
  - A request without `Accept` (or with `*/*`) gets its response in the media type of its body when the response
    has it: a SOAP 1.2 request (`application/soap+xml`) gets a SOAP 1.2 envelope rather than the first media type
    listed.
- **`diff` rates a component schema by where it is used.** An OpenAPI component schema referenced only from
  parameters and request bodies (following the references between schemas, in either document) gets the `request`
  rules, one referenced only from responses the `response` rules; before, every component schema got the stricter of
  the two, so removing a property from a request-only schema, or adding a required one to a response-only schema, was
  breaking. Schemas used both ways, or not at all, are rated as before. Callbacks and webhooks swap the directions, as
  they always did.
- The GraphQL contract checks of `apigenie test` and of `apigenie-server`'s GraphQL proxy warn about field errors
  (`response.field-error`): every error of an operation the server ran, next to `data` that is `null` or partial.
  Before, such answers passed silently. A server answering every field with an error passed `apigenie test
  --generate` with no violations. `--fail-on warnings` fails on them; `--severity` or `contract.severity` changes the
  level. Errors without `data` stay `response.request-error`.
- `apigenie-mock` is renamed `apigenie-server`, with `apigenie-mock` and the `APIGENIE_MOCK_*` variables kept as
  deprecated aliases until 1.1, and the `mykulyak/apigenie-server` Docker image (see Upgrading).
- `i18n apply` translates only the texts `i18n extract` extracts from OpenAPI, Swagger and AsyncAPI specs: a key
  pointing to another string, such as an `operationId` or a URL, is now reported as addressing nothing (a warning, an
  error with `--strict`) instead of being applied, and a key pointing to an object is no longer an error. The spec must
  be valid.
- The OpenAPI reader reads the schemas under `$defs`, `dependentSchemas` and `additionalItems` as schemas, so `lint`
  rules, `generate` and the other commands see them; `$defs` and `dependentSchemas` are written after
  `patternProperties`.
- Loading translations into the `Translator` (`apigenie-generator docs --i18n`) is atomic: an invalid file changes
  nothing, and the error names the locale and the key. Empty translations are skipped, so the source text is shown.
- JUnit reports (`--report-junit` of `apigenie-server` and `apigenie test`) escape element content and attribute values
  separately: quotes in `<failure>` and `<system-out>` text are written as they are, line breaks in attribute values
  as `&#xA;`, and characters XML can't carry as U+FFFD instead of `?`.
- `response.body.unvalidatable` no longer covers XML bodies, which are now checked.
- File errors name their cause: "Failed to open file: openapi.yaml (not found)." instead of "Failed to open file:
  openapi.yaml.".
- The notes "not checkable over MQTT 3.1.1" of `apigenie test` appear only for regions that speak MQTT 3.1.1; over
  MQTT 5 header correlation ids and reply addresses are checked. A broker's MQTT 5 refusal names its reason code
  (`reason code 0x86 (bad user name or password)`).

### Deprecated

- `version` in the contract report of `apigenie-server` and in the `apigenie test` report: it duplicates
  `formatVersion` and will be removed in the next release.

### Removed

- `apigenie credits` no longer lists TinyXML2, which API Genie stopped using long ago.

### Fixed

- Bidirectional gRPC session replay preserves recorded response order when several requests arrive
  before the initial replies are sent, including when mock latency delays those replies.

- Format checks of numbers: `format: int32`, `int64`, `float` and `double` were only applied to strings, so they
  rejected every string and never checked a number. A format now applies to its JSON types: int32 checks that a
  number is an integer in range (1.0 counts), and a string under it is left to `type`. `format: password` no longer
  rejects an empty string.

- The gRPC answers `apigenie-server` generates set the fields marked `(google.api.field_behavior) = REQUIRED`,
  messages, lists and maps included, and not to their default values, so a validating proxy in front of the mock
  no longer reports `response.message.incompatible` for its own answers; fields marked `INPUT_ONLY` are left out.
  The requests of `apigenie test --generate` for `.proto` files set REQUIRED fields too and leave out `OUTPUT_ONLY`
  ones. A REQUIRED field whose message would contain itself stays optional.
- The gRPC checks of `apigenie-server` (mock and `--proxy-to`) and `apigenie test` report a field whose wire type isn't
  its declared type's, such as a string where the `.proto` file declares an `int64`. Decoding drops such a field, as
  protobuf parsers do, so the message used to pass as if the field were absent. It is now
  `request.message.incompatible` or `response.message.incompatible` (code `wire-type`), at the field's location, and
  the mock in enforce mode refuses such a request with INVALID_ARGUMENT.
- `@mykulyak/apigenie-docs` is published on npm (2026-10-11, `docs-0.1.0`). The 0.9.0 release notes said that the
  web components were "on npm" before they had been published, and under their old name. The release gate now
  installs and builds a generated docs project against the npm registry, so a CLI can't be released while the
  package it depends on is missing or out of range.
- `format --output` with more than one input, or with an output file of an unknown extension, failed with an empty
  error message; it now says what's wrong.
- `license --library` with an unknown name printed its error on the standard output.
- `apigenie-server` answered `Accept: application/xml` with a JSON body under an XML `Content-Type`.
- Paths longer than 260 characters work on Windows, without the system-wide long-path setting.
- `test import --output` no longer fails when the output directory's name contains a dot (`--output api.v2`): the
  directory used to be mistaken for a file and left uncreated.
- `lint --fix` and the other writers that replace a file in place create their temporary file exclusively, next to
  the target, and never leave it behind.
- Faker's IBANs have valid check digits, routing numbers a valid ABA checksum, `book.isbn` a valid ISBN-13 check digit,
  and Polish, US, Spanish and British national ids follow their rules.
- Faker's full names use one sex for first and last names, female middle names are generated, git commit dates name
  their own weekday, and usernames get their `.`, `_` and `-` separators back.
- JSON output writes empty objects and arrays as `{}` and `[]` instead of spreading them over three lines with a blank
  one in between (`format`, `diff` and `changelog` JSON reports, `lint --formatter json` and `sarif`, docs bundles).
- `property_order.paths` was ignored: `/paths` was ordered by the default order.
- `property_order.reference` was never applied: Reference Objects are recognized by their `$ref`, except in schemas,
  where `$ref` is a keyword, and in path items that have their own operations.
- The error for an `openapi.custom_formats` that is not an array said an object was expected; errors in the
  configuration file now name the file and the position.
- `apigenie-server` named no file in its error for an invalid configuration file that it found itself.

## 0.9.0 (2026-10-10)

API Genie 0.9.0 translates OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files, and its mock server
(`apigenie-mock`, now `apigenie-server`) mocks and contract-checks HTTP, WebSocket, MQTT, gRPC and GraphQL APIs. The
new GitHub Action `mykulyak/api-genie-action` installs the CLI in workflows on Linux, macOS and Windows.

### Highlights

- **Translations for all five standards.** `apigenie i18n extract` and `i18n apply` work on OpenAPI, Swagger 2.0,
  AsyncAPI, Protobuf and GraphQL files: the texts are extracted keyed by JSON pointers, declaration names or schema
  coordinates, and translations are put back without touching the rest of the file
  ([i18n](https://apigenie.pl/docs/reference/cli/i18n)).
- **Contract testing across OpenAPI, Swagger, AsyncAPI, gRPC and GraphQL, with TLS.** `apigenie test` runs `.http`
  files (HTTP, gRPC, WebSocket, MQTT and GraphQL requests) and generated requests against a live API, and
  `apigenie-mock --proxy-to` sits between clients and a real server or broker (HTTP, WebSocket, MQTT, gRPC, GraphQL),
  checking every request and response against the contract. Both report coverage, JSON and JUnit reports, and fail
  CI with `--fail-on` and `--min-coverage`. TLS is supported throughout: the mock serves HTTPS, WSS and gRPC over TLS
  (`--tls-cert`, `--tls-key`), and requests and upstreams can be `https://`, `wss://` and `mqtts://`, verified against
  the system's CA certificates (`--ca-cert`, `--insecure`) ([test](https://apigenie.pl/docs/reference/cli/test),
  [mock server](https://apigenie.pl/docs/reference/server)).
- **Code generation for five stacks.** Clients and servers for TypeScript (fetch, Express, oRPC, WebSocket, Kafka on
  KafkaJS, Zod), Python (httpx, FastAPI, FastStream), Go (`net/http`, Kafka), Java (Spring clients and servers, Kafka)
  and C# (`HttpClient`, ASP.NET Core, Kafka), from OpenAPI 3.0–3.2 and, for event-driven APIs, AsyncAPI 3.x. Every target
  is checked by a conformance suite: snapshots, the target's own compiler and linter, and a run against
  `apigenie-mock --proxy-to`. The generators are a separate executable, `apigenie-generator`, installed with the CLI
  ([apigenie-generator](https://apigenie.pl/docs/reference/generator)).
- **Web components for every spec type, and `generate docs`.** The `apg-*` custom elements
  (`@mykulyak/apigenie-web-components` on npm) document OpenAPI, Swagger 2.0, AsyncAPI, Protobuf/gRPC and GraphQL
  APIs, with Try it out for HTTP and GraphQL, built on the same engine as the CLI compiled to WebAssembly.
  `apigenie-generator docs` compiles any of these files, several at once, into a docs bundle that the components
  render into a static site (`npm install && npm run build`), with translations, the git changelog and example
  files; it replaces `generate doc html` (see Upgrading).

### Upgrading

- **`apigenie generate` is now `apigenie-generator`.** The code generators moved out of `apigenie` into a separate
  executable, `apigenie-generator`, installed next to it by every archive and package, the npm package and Homebrew,
  and included in the `mykulyak/apigenie` Docker image (`docker run --entrypoint apigenie-generator ...`). Drop
  `generate` from the command line: `apigenie generate client fetch spec.yaml -o out` becomes
  `apigenie-generator client fetch spec.yaml -o out`. The options and the `commands.generate` section of the
  configuration file are unchanged; `apigenie generate` fails as an unknown command. The banners of generated files
  name the new command. The entries below still call the generators `generate <target>`. The design is ADR-123.
- **`generate doc html` is replaced by `generate docs`**, with no alias. `apigenie-generator docs openapi.yaml -o docs`
  replaces `apigenie generate doc html openapi.yaml --output docs`; it takes several inputs of mixed families (OpenAPI,
  Swagger 2.0, AsyncAPI, GraphQL, Protobuf) and makes one site, and `-c/--config`, `--i18n LOCALE=FILE`,
  `--package-name` and `--package-version` keep their meaning. The output is no longer an Astro project but a docs
  bundle (`apigenie-docs.json` and `documents/<id>/document.<locale>.json`, ADR-122) with a `package.json` that
  depends on `@mykulyak/apigenie-web-components` instead of `@mykulyak/api-genie-doc-html-template`;
  `npm install && npm run build` still builds the static site, now into `dist/`, prerendered from the web components.
  `--bundle-only` writes the bundle alone, for a site built by other means. The CLI does not run Node. The
  configuration section `commands.generate.doc_html` is `commands.generate.docs`: `html_title_prefix` is `title`,
  `i18n.default_locale` and `i18n.prefix_default_locale` move to the top of the section (the locales come from
  `--i18n`), `changelog` keeps its name (also `--changelog`), and `documents` lists the inputs (`file`, `id`,
  `title`, `proto_paths`, `examples`). `pages`, `operations`, `resources`, `search`, `sidebar`, `html_meta`,
  `template`, `openapi_schema`, `request_code_examples`, `use_request_body_examples`, `generate_response_schema`,
  `use_response_examples` and `fail_on_generator_error` described the Astro layout and have no replacement: the site
  has the layout of `<apg-api-reference>` (navigation with search, one page per operation and schema), themed with
  the components' CSS custom properties and `::part()`. Generated Astro projects keep building with the template they
  depend on, but nothing regenerates them: run `generate docs` into a new directory.
- **New dependency: Mbed TLS.** `apigenie` and `apigenie-mock` link Mbed TLS 3.6 (Apache-2.0) for `https://`,
  `wss://` and `mqtts://` connections; release binaries grow by about 0.9 MB. Builds from source get it from vcpkg
  (`mbedtls >= 3.6.2`). Verifying servers needs the system's CA certificates: the Docker images now include them; in
  your own minimal images install `ca-certificates`. `apigenie credits` and `apigenie license --library mbedtls` list
  it.
- **Telemetry is opt-in.** The CLI no longer writes `.apigenie.telemetry` in the current directory, and sends
  nothing. Set `APIGENIE_TELEMETRY_FILE` to a path to keep a local telemetry log; old `.apigenie.telemetry` files
  can be deleted.
- **`i18n` has subcommands.** `apigenie i18n FILE --output DEST` becomes `apigenie i18n extract FILE --output DEST`.
- **`lint` fails on errors.** `lint` exits with status 1 when issues of severity `error` remain (after `--fix`), so CI
  jobs that ran it only for its report fail now; lower the severities in the configuration to keep them passing.
- **`apigenie-mock --stubs`** with a GraphQL schema or an AsyncAPI document exits with status 2 instead of ignoring
  the option.

### Added

- `generate docs` documents OpenAPI, Swagger 2.0, AsyncAPI, GraphQL and Protobuf files, several at once, as one static
  site: it writes a docs bundle (`apigenie-docs.json`; per document and locale the resolved document, or the
  documentation model of AsyncAPI, GraphQL and Protobuf files; with `--changelog` the git changelog, as `apigenie
  changelog` computes it; the example files next to a GraphQL schema and those listed in the configuration) and the
  npm project that renders it with `@mykulyak/apigenie-web-components` (`npm install && npm run build`): prerendered
  pages with declarative shadow DOM that hydrate in the browser, Try it out, a sitemap, a locale switcher for the
  `--i18n` locales, a changelog page and the examples. `--bundle-only` writes the bundle alone. Internal: the
  `docs_bundle` library (`compileDocsBundle`), `changelog_helpers` (the changelog of any family, shared with the
  `changelog` command), and `graphql_describe` and `protobuf_describe`, which write the documentation models that the
  `graphql` and `protobuf` WebAssembly modules used to write themselves, as `asyncapi_describe` does for AsyncAPI.
  The design is ADR-122.
- `generate server spring` (OpenAPI) routes QUERY operations and `additionalOperations` such as COPY: their handlers
  carry `@ExtensionMethod("QUERY")`, which the generated `ExtensionMethodConfiguration` matches through a custom
  request condition of the request mapping (`WebMvcRegistrations`, or `WebFluxRegistrations` with `reactive=true`).
  `pipeDelimited` and `spaceDelimited` array query parameters are split on their separator (`@DelimitedParameter`),
  and query parameters with JSON `content` are read as JSON into their model (`@JsonParameter`), which is null and
  left unvalidated when the parameter is absent; both converters are registered by `ParameterConversionConfiguration`.
  Request media types whose bodies have different types get a handler each, named as the methods of
  `generate client java` (`updateShipment` for `application/merge-patch+json`, `updateShipmentWithJsonPatch` for the
  `application/json-patch+json` array). The new `ApiExceptionHandler` answers invalid requests with a 400 Problem
  (`type`, `title`, `status`, `detail` and, for constraint violations of the parameters, `errors` with the `name`,
  `path` and `message` of each), where a `ConstraintViolationException` used to answer 500. Conformance Level 3 of the
  target only expects the x-internal operation, which servers leave out, to fail.
- `generate server aspnet` (OpenAPI) falls back to the default mapping of a discriminator (`defaultMapping`, or
  `x-defaultMapping` before 3.2): unions are read and written by the converters of `generate client csharp`, written
  next to the abstract record and attached with `[JsonConverter]` instead of `[JsonPolymorphic]`, so a missing or
  unmapped discriminator reads as the default type, and the discriminator may be anywhere in the object on .NET 8 too.
  Request media types whose bodies have different types get an endpoint and API method each, named as the methods of
  the C# client (`UpdateShipment` for `application/merge-patch+json`, `UpdateShipmentJsonPatch` for the
  `application/json-patch+json` array) and restricted to their media types with `Accepts<T>()`, so routing picks the
  endpoint by Content-Type; the JSON Patch array used to be bound as a `ShipmentPatch` object (400). Conformance Level 3
  of the target passes with only the x-internal operation, which the server leaves out, expected to fail.
- The codegen conformance runner decides that the x-internal operations of the fixture are expected to fail for servers
  that leave them out: `omitsInternalOperations` on a Level 3 entry of `tests/conformance/targets.json` (set for the
  ASP.NET and Spring servers) expects every request of those operations, the request set's and the generated one, to
  fail, instead of hand-written `expected` entries; a server that starts serving one still fails the level.
- `generate client kafkajs` and `generate server kafkajs` generate TypeScript (Node.js) packages for the Kafka channels
  of AsyncAPI 3.x documents, on KafkaJS 2.2.4: the server for the described application (`KafkaApp`, taking a handler
  per received operation, with `start()` and `stop()`), the client for its counterpart (`KafkaClient`, with `connect()`,
  `listen<Operation>(handler)` and `close()`); `perspective` swaps either. Every sent operation gets a sender with a
  `send<Message>(message)` method per message, which validates the message, writes the constant headers (e.g.
  `ce_type`), the key and the topic, and, for an operation with a reply, sends the request with a new correlation id
  unless it has one and resolves with the typed reply, matched by correlation id on one reply consumer per operation
  (`ReplyTimeoutError` when none arrives in time). Received operations get handler interfaces with `on<Message>(message,
  record)` and `onUnknown`, dispatched by `ce_type` header, payload property or deduction; repliers return the reply,
  sent with the request's correlation id. Payloads are validated by dependency-free functions generated from the schemas
  (`MessageValidationError`), headers by their constraints. Avro payloads, topics with parameters and replies at
  runtime-expression addresses are skipped with a warning. Configured under `commands.generate.client_kafkajs` and
  `commands.generate.server_kafkajs` (`layout`, `import_extension`, `perspective`, `validation`); the design is ADR-120.
  The codegen conformance suite checks both commands in both perspectives at Levels 1 and 2 (`tsc` and ESLint) and, at
  Level 3, runs the client against the server on the Kafka service container both ways, as for Go and C#.
- `generate client ws` and `generate server ws` generate the replies of operations whose `reply` is on the request's
  channel: the client gets typed `on<Message>` handlers for the reply messages and, when the messages have a correlation
  id in their payloads, `request<Operation>(payload, { timeoutMs })` resolving with the reply carrying the request's id;
  the server session gets `send<Message>` methods for them and `replyTo<Operation>(request, reply)`, which copies the
  request's correlation id into the reply. On the AsyncAPI conformance fixture, `requestPickup()` and
  `replyToRequestPickup()`. Replies on another channel or at a runtime-expression address are still reported as
  unsupported.
- `apigenie test` sends WS regions to `wss://` and MQTT regions to `mqtts://` (or `ssl://`) URLs, with ports 443 and
  8883 by default. Their certificates are checked as for `https://`, with SNI and the URL's host name, so `--ca-cert`
  and `--insecure` apply. MQTT regions send their `username` and `password` settings in CONNECT (MQTT 3.1.1). A setting
  the region doesn't give comes from `APIGENIE_MQTT_USERNAME` and `APIGENIE_MQTT_PASSWORD`. A refusal names the reason
  (bad user name or password, not authorized). Credentials show as `[redacted]` in the console and the JSON and JUnit
  reports, as OAuth 2 secrets do, and a URL's `user:password@` is shown as `***@`. These URLs used to fail with "speaks plain WebSocket/MQTT only", and the
  credentials were noted as not sent. MQTT 5 is still not supported. The design is the amendment of ADR-110.
- `apigenie test` with an AsyncAPI `--spec` checks HTTP requests against the document's HTTP channels, with the code
  and checks of the validating proxy: the channel and operation by path and method (a `receive` operation's HTTP
  binding's method, GET for a `send` one) or by `# @operation`, a `receive` operation's body, query and header fields
  against its messages and a 2XX response against its reply, a `send` operation's response against its messages. The
  requests count for their operations in the coverage, which used to show them as not tested, and `--generate` sends
  one request per HTTP channel operation (to `--base-url`, a `ws://` URL taken as `http://`). A path of no HTTP
  channel is a note. Both `apigenie test` and `apigenie-mock --proxy-to` now check the `query` of an operation's HTTP
  binding (`operation.query.invalid`) and the header fields of a message's `headers` and HTTP binding `headers`, its
  traits' included (`message.headers.invalid`); responses other than 2XX are still not checked. The design is
  ADR-118, which amends ADR-110 and ADR-112.
- `apigenie test` runs httpYac's OAuth 2 authorization instead of skipping it: `Authorization: oauth2 [GRANT]
  [PREFIX]` (and `openid`) with the `client_credentials`, `password` and `refresh_token` grants requests a token from
  `<prefix>_tokenEndpoint` (or the OpenID Connect discovery document of `<prefix>_issuer`) with the `<prefix>_clientId`,
  `_clientSecret`, `_scope`, `_audience`, `_username`, `_password` and `_useAuthorizationHeader` variables, keeps it
  for the run, requests it again (with its refresh token) when it expires, and sends `Authorization: Bearer <token>`.
  Token endpoints are reached like other requests, `https://` included (`--ca-cert`, `--insecure`); a refused token
  request fails its request, which isn't sent. The `authorization_code`, `implicit` and `device_code` grants are still
  skipped, with a reason naming the grant. With `--spec`, requests sent with a token are checked by the new
  `request.authorization.oauth2-scheme` and `request.authorization.oauth2-scope` warnings (the operation has no OAuth 2
  scheme, the requested scopes aren't its). Tokens, client secrets, passwords and `Authorization` credentials show as
  `[redacted]` in the output, the reports and warnings. `apigenie test import` maps Postman's client credentials and
  password grants to these variables instead of disabling the requests. The design is ADR-117.
- The `asyncapi` WebAssembly module (`asyncapi.mjs`, and `asyncapi.web.mjs` for browsers) exports
  `describe(text, {fileName, files})`. It returns the documentation model of an AsyncAPI 3.0 or 3.1 document as plain
  JSON (`{"apigenieAsyncAPI": 1, …}`):
  - servers, channels, operations and messages with their JSON pointers and source positions;
  - references followed and external files given in `files` bundled as `apigenie asyncapi bundle` does;
  - traits applied with JSON Merge Patch, and the defaults of the specification;
  - headers and payloads as schemas (other formats, such as Avro, kept with their `schemaFormat`), and a position
    table;
  - the problems found as `issues`.

  AsyncAPI 2.x is an error. It is built on the new `asyncapi_describe` library; the JSON Merge Patch of traits moved
  into the `asyncapi` library (`asyncapi/traits.hpp`), where the models generators use it too. ADR-119 has the design.
- `apigenie-mock`, its validating proxy (`--proxy-to`) and `apigenie test --spec` take Swagger 2.0 documents: they
  convert them to OpenAPI 3.2 in memory, as `convert --to openapi32` does, each time the document is read, and write
  no file. Locations stay those of the Swagger file: the lines of warnings, the lines and JSON pointers of
  `x-apigenie-mock` problems, and the new `pointer` of each operation in the contract reports. What the conversion
  can only approximate is told once at startup as `info:` lines with the Swagger file's line and JSON pointer
  (`{"event":"info"}` with `apigenie test --formatter json`). Swagger 2.0 documents used to be refused with exit
  status 3.
- `apigenie-mock --proxy-to mqtt://host:port` (or `mqtts://`, verified like `https://` upstreams) with an AsyncAPI
  document contract-tests a real MQTT broker: the mock's broker relays, each client getting a connection of its own to
  the broker with its identifier, version, clean start, keep-alive, will and credentials, and the broker's CONNACK and
  SUBACK. Every PUBLISH is checked against the topic's channel: what clients publish against its `receive` operations,
  with the QoS of their MQTT binding (`message.qos.unexpected`), what the broker delivers against its `send` operations
  (a channel without them: its `receive` operations and the replies sent there). In enforce mode invalid messages
  aren't forwarded (MQTT 5 clients get reason code 0x99). Wills, refusals and an unreachable broker (server
  unavailable) are passed on, clients stay connected across reloads, the log has `mqtt-connect` and `mqtt-disconnect`
  events, and coverage, `--report`, `--report-junit`, `--fail-on` and `--min-coverage` work as for WebSocket.
  `--proxy-to` can be repeated to proxy a WebSocket server and an MQTT broker at once (`proxy.target` takes a list).
  The design is ADR-112, which supersedes parts of ADR-097.
- An AsyncAPI document's HTTP channels are proxied to the `http(s)://` or `ws(s)://` server of `--proxy-to` through
  the OpenAPI proxy's transport and checked against the AsyncAPI document: a `receive` operation's request body against
  its messages and a 2XX response's body against its reply, a `send` operation's response (GET) against its messages.
  In enforce mode invalid requests get 422 and invalid responses are replaced by 502; paths of no channel get 404 or
  405.
- The AsyncAPI checks have `channel.parameter.invalid`: a value of an address parameter (a topic level, a path segment)
  outside the parameter's `enum`, for WebSocket, MQTT and HTTP channels.
- `mqtt::ClientConnection`, an MQTT 3.1.1 and 5 client on the event loop (over TLS too), and broker hooks that decide
  CONNECT and SUBSCRIBE later and let the owner relay instead of delivering.
- `apigenie test` runs GraphQL requests instead of skipping them: `GRAPHQL URL` requests of httpYac and the JetBrains
  HTTP client (the query, then its variables as JSON after a blank line; `# @operation` is the `operationName`) and
  `POST` requests whose body is a query are sent as GraphQL over HTTP, and JSON `{"query": ...}` bodies as they are.
  With a GraphQL schema as `--spec` (`.graphql`, `.graphqls`, `.gql`), each operation is validated against the schema
  before it is sent (an invalid one fails its request, not the run, and isn't sent), and each response is checked as
  `apigenie-mock --proxy-to` checks it: the shape of `data` and `errors`, value types, `null` in non-null fields that no
  error explains, `__typename` of abstract types and schema drift. Coverage is per field and per root field
  (`--min-coverage` is the share of fields), and `--report` and `--report-junit` are the GraphQL contract report of
  `apigenie-mock` with the run's `tests` and `requests`. `--generate` sends one request per field of `Query` and
  `Mutation`, with required arguments made up from their types as the mock makes up values; `--base-url` is the
  endpoint. `--severity` takes the GraphQL checks. The design is ADR-111; the GraphQL contract report moved from the
  `apigenie-mock` executable into the `graphql_mock` library, with the same output.
- `apigenie test` runs httpYac's `WS` and `MQTT` requests and checks their messages against an AsyncAPI 3.x `--spec`.
  A region connects to a `ws://` server or an `mqtt://` broker (MQTT 3.1.1; `topic`, `publish`, `subscribe`, `qos`,
  `retain` headers), sends the messages of its body (separated by `===`, `=== wait-for-server`) and waits for the
  server's until `# @expect N` came or `# @timeout` (`--message-timeout`, 5000 ms) passed; the messages received are
  the response, a JSON array (`?? body $[0].type == pickup.confirmed`, `?? body $.length == 2`, `response.messages` in
  scripts). The channel comes from the URL's path or the topic (`# @channel` names it); messages sent are checked
  against the channel's receive operations and messages received against its send operations, with the AsyncAPI
  proxy's checks. A message of a request/reply operation is paired with its reply, checked by the new contract checks
  `message.reply.missing` (warn) and `message.reply.uncorrelated` (error, a payload `correlationId` that differs);
  correlation ids and reply addresses in message headers are noted as not checkable over MQTT 3.1.1. Coverage per
  operation and message and the reports (`--report`, `--report-junit`, `--formatter json`, `--min-coverage`) are the
  AsyncAPI proxy's. `--generate` sends a region per WebSocket and MQTT channel with the receive operations' example
  messages, at `--base-url ws://...` and the new `--mqtt-url`. The design is ADR-110, extending ADR-136 and ADR-097.
- `apigenie-mock --proxy-to` contract-tests a real gRPC server against its `.proto` file: the proxy checks the
  upstream's messages against their output types (also fields marked `[(google.api.field_behavior) = REQUIRED]`,
  under proto3's presence rules, and deprecated fields and enum values), its status (HTTP status, content type,
  `grpc-status`, the percent-encoding of `grpc-message`, `grpc-status-details-bin` as a `google.rpc.Status` whose code
  is `grpc-status`), the number of messages of unary calls and the `-bin` metadata, with check ids such as
  `response.message.incompatible` and `response.status.details-incompatible` that `contract.severity` changes.
  Locations name the field (`message[0]/items/2/sku`). It counts the calls of each service and method, and writes the
  contract reports the OpenAPI, GraphQL and AsyncAPI proxies write (`--report` with `"specification": "grpc"`,
  `--report-junit` with a test case per method, `--fail-on`, `--min-coverage` as the share of methods, exit status
  5, `GET /__apigenie/contract`). `--strict` (or `grpc.validation.response: enforce`) checks each upstream message
  before forwarding it and fails the call with INTERNAL. The upstream is `HOST:PORT` (cleartext HTTP/2) or
  `https://host[:port]` (HTTP/2 over TLS). The design is ADR-109.
- `apigenie test` sends `GRPC` requests of `.http` files (httpYac's `GRPC host:port/package.Service/Method` with the
  request message as a proto3 JSON body, metadata as headers) with a `.proto` file as `--spec`, its imports looked up
  in the new `--proto-path` directories. Unary and server-streaming calls are made over HTTP/2, cleartext or over TLS
  for `grpcs://` URLs (with `--ca-cert` and `--insecure`), and checked like the proxy's; a body that isn't a valid message fails the request with the field's path before it is sent.
  Assertions and scripts see the status code as `status` (`?? status == 0`), metadata and trailers as headers and the
  message as a JSON body (an array for server streaming). Client- and bidi-streaming requests are reported as skipped
  with a warning. `--generate --base-url HOST:PORT` (or `grpcs://HOST:PORT`) sends a request per method with a
  generated message. The
  reports are the gRPC contract report plus the requests (`grpc`, `grpcStatus`).
- `apigenie-mock --tls-cert FILE --tls-key FILE` serves HTTPS, WSS and gRPC over TLS. Clients that ask for `h2` by
  ALPN, such as browsers and gRPC clients, get HTTP/2. The settings are also `tls.cert` and `tls.key` in the
  configuration, and `APIGENIE_MOCK_TLS_CERT` and `APIGENIE_MOCK_TLS_KEY`. A separate admin port uses the same
  certificate, and the MQTT broker stays cleartext. The startup line shows `https://` and `wss://` URLs and
  `"tls": true`. TLS 1.2 and 1.3 come from Mbed TLS; the design is ADR-104.
- `apigenie-mock --proxy-to` reaches TLS upstreams: `https://` for the OpenAPI and GraphQL validating proxies,
  `wss://` for the AsyncAPI WebSocket proxy, and `https://host[:port]` for gRPC (HTTP/2 over TLS with ALPN `h2`,
  shown as `grpcs://`). Certificates are verified against the system's roots: the macOS keychains, the Windows ROOT
  store, the Linux CA bundle, or `SSL_CERT_FILE` and `SSL_CERT_DIR`. `--ca-cert FILE` (repeatable; `tls.ca_certs`,
  `APIGENIE_MOCK_CA_CERT`) adds authorities, and `--insecure` (`tls.insecure`, `APIGENIE_MOCK_INSECURE=1`) skips
  verification. A rejected certificate gets the usual 502 with the reason.
- `apigenie test` sends `https://` requests, with the same `--ca-cert FILE` and `--insecure` options. Imported
  collections no longer need their HTTPS URLs pointed at a cleartext server.
- `generate server go` also takes AsyncAPI 3.x documents and generates a Go module (Go 1.22) for their Kafka channels
  on franz-go (`github.com/twmb/franz-go/pkg/kgo`, pinned at v1.18.1, with a complete `go.sum`): structs, enums and
  sealed-interface unions with `json` tags and `Validate` methods for the payloads, a struct per message (key, typed
  headers, payload) validated before it is sent and after it is received, and an `App` with a consumer group and a
  handler interface per receive operation (several messages told apart by a constant payload property or header, e.g.
  the `ce_type` of binary-mode CloudEvents; others go to `OnUnknown`) and a typed sender per send operation. Request/reply
  operations with a reply channel return the reply from the sender, matched by its correlation id, and repliers send the
  handler's reply with the correlation id copied. Consumer groups and client ids come from the Kafka operation bindings.
  `cmd/<package>/main.go` takes the brokers from `-brokers` or `KAFKA_BROKERS`, wires stub handlers and stops cleanly on
  SIGINT and SIGTERM. Channels of other protocols are skipped with an info line, Avro payloads with a warning. Configured
  under `commands.generate.server_go.asyncapi`; the design is ADR-105. The codegen conformance suite checks both
  perspectives at Levels 1 and 2 and, at Level 3, has the application and the counterpart exchange the fixture's Kafka
  messages on the conformance workflow's new Kafka service container, including the `requestLabelRender` reply, an
  unknown `ce_type` and an invalid payload.
- `generate client go` also takes AsyncAPI 3.x documents and generates a Go Kafka client package (a Go 1.22 module on
  franz-go v1.18.1, without `main.go`), by default for the counterpart of the described application and with
  `perspective: application` for the application itself. `NewClient(options)` creates the producer, `Close()` closes
  every client, and `Options` takes the brokers, a client id and franz-go options passed to every client. A send
  operation gets `Send<Operation>(ctx, message)`, which writes the constant headers (e.g. `ce_type`), the key and the
  topic from the bindings; with several messages it takes an interface they implement. A request/reply operation gets
  a blocking `Request<Operation>(ctx, message)` that sets a fresh correlation id, waits for the reply until the
  context's deadline and returns it typed (an interface of the replies when there are several), with one reply
  consumer per operation shared by all requests. A receive operation gets `Listen<Operation>(handler)`, consuming in the
  background with the server's dispatch, validation and repliers. Configured under
  `commands.generate.client_go.asyncapi`; the design is ADR-106. The codegen conformance suite checks both perspectives
  at Levels 1 and 2 and, at Level 3, runs the client against `generate server go` on the Kafka service container both
  ways: the server's events and label requests reach the client's listeners and replier, and the client's sends and
  requests (concurrent ones and one ending at its context's deadline included) reach the server's handlers.
- `Options.ClientID` of the Go Kafka code of `generate server go` and `generate client go` replaces the producer's
  client id.
- `generate server aspnet` also takes AsyncAPI 3.x documents and generates an ASP.NET Core project (.NET 8) for their
  Kafka channels on Confluent.Kafka 2.15.1, so a REST API and its events can live in one application: the payload models
  of `generate client csharp` (records, enums, unions read by converters of the System.Text.Json source-generated
  context), a record per message (key, typed headers with DataAnnotations, payload) validated before it is sent and
  after it is received, and per receive operation a handler interface, registered with dependency injection and resolved
  per record, and a consumer hosted as a `BackgroundService` in the operation's consumer group (several messages told
  apart by a constant payload property or header, e.g. the `ce_type` of binary-mode CloudEvents; others go to
  `OnUnknownAsync`). Records are committed once their handler returns and handled again when it throws; invalid
  records are logged and committed. Each send operation gets a typed sender; request/reply operations with a reply
  channel return the reply from `Request<Message>Async`, matched by correlation id, and repliers send the handler's
  reply with the correlation id copied. The `AsyncApi:Kafka` section of `appsettings.json` holds the brokers, topics,
  group and client ids (from the Kafka operation bindings) and further librdkafka properties, overridable by
  environment variables; stopping the host closes the consumers. Configured under
  `commands.generate.server_aspnet.asyncapi`; the design is ADR-107. The codegen conformance suite checks both
  perspectives at Levels 1 and 2 and, at Level 3, runs the application and the counterpart on the conformance
  workflow's Kafka service container, as for Go.
- `generate client csharp` also takes AsyncAPI 3.x documents and generates a C# Kafka client library (.NET 8 class
  library on Confluent.Kafka 2.15.1), by default for the counterpart of the described application and with
  `perspective: application` for the application itself. `<Name>KafkaClient` has a producer per channel it sends to,
  whose `Send<Message>Async` writes the constant headers (e.g. `ce_type`), the key and the topic from the bindings; a
  request/reply operation gets `Request<Message>Async`, which sets a fresh correlation id, waits for the reply with a
  timeout (`ReplyTimeout` or an argument) and a `CancellationToken`, and returns it typed (an interface of the replies
  when there are several), with one reply consumer per client and a pending request per correlation id. Receive
  operations get the handler interfaces and hosted consumers of `generate server aspnet`, with its dispatch,
  validation and repliers. `Add<Name>KafkaClient(configuration, configure)` binds the options to the `AsyncApi:Kafka`
  section and registers the client and its producers, and its builder's `Add<Operation>Handler<THandler>()` registers
  a handler with its consumer. `--package-name` is the root namespace (default: the title followed by `.Client`), as
  for OpenAPI. Configured under `commands.generate.client_csharp.asyncapi`; the design is ADR-108. The codegen
  conformance suite checks both perspectives at Levels 1 and 2 and, at Level 3, runs the client against
  `generate server aspnet` on the Kafka service container both ways, including concurrent requests, a request timing
  out and a cancelled one.
- `generate client java` also takes AsyncAPI 3.x documents and generates a Java Kafka client library (a Maven project
  for Java 21 on the Apache Kafka client 4.1.0, Jackson and Hibernate Validator, without Spring), by default for the
  counterpart of the described application and with `perspective: application` for the application itself. It shares
  the message records, models, dispatch, validation and repliers of `generate server spring`. `<Name>KafkaClient`
  (with `<Name>KafkaClientOptions`: servers, topics, client and group ids, reply timeout, producer and consumer
  properties) gets `send<Message>(message)` per send operation, writing the constant headers (e.g. `ce_type`), the key
  and the topic from the bindings; `<operation>(message[, timeout])` per request/reply operation, which sets a fresh
  correlation id (header, payload pointer or `kafka_correlationId`) and completes with the typed reply, with one
  group-less reply consumer per client; and `listen<Operation>(handler)` per receive operation, consuming on a virtual
  thread with `onUnknown` and `onError` defaults. `--library` and `-p` are errors with AsyncAPI input. Configured under
  `commands.generate.client_java.asyncapi`; the design is ADR-121. The codegen conformance suite checks both
  perspectives at Levels 1 and 2 (`mvn package`, `javac -Xlint:all -Werror`) and, at Level 3, runs the client against
  `generate server spring` on the Kafka service container both ways, including concurrent requests and a timeout.
- `generate client python` also takes AsyncAPI 3.x documents and generates an asyncio Kafka client package on aiokafka
  with the Pydantic models of `generate server faststream`, by default for the counterpart of the described application
  and with `perspective: application` for the application itself. `messages.py` has a dataclass per message (payload,
  headers, key) with headers models and their constant headers; `<Name>KafkaClient`, an async context manager, gets
  `send_<message>()`, `request_<operation>(message, *, timeout=None)` (fresh correlation id, typed reply, one
  group-less reply consumer per client, `TimeoutError`) and `listen_<operation>(handler)` with abstract handler classes
  (`on_unknown` and `on_error` defaults), by the Kafka rules of ADR-102. The package passes `mypy --strict` and ruff,
  and depends on `aiokafka[lz4,snappy,zstd]`, so it reads topics other producers compress.
  Configured under `commands.generate.client_python.asyncapi`; the design is ADR-121. The codegen conformance suite
  checks both perspectives at Levels 1 and 2 and, at Level 3, runs the client's counterpart against the Kafka broker of
  `generate server faststream`'s application and the client's application against its counterpart on the Kafka service
  container, including concurrent requests and a timeout.
- `generate server spring` also takes AsyncAPI 3.x documents and generates a Spring Boot application (Maven project)
  for their Kafka channels: a record per payload and per message (key, payload, headers) with Jackson and Jakarta Bean
  Validation annotations, a `@KafkaListener` and a handler interface per receive operation (several messages told apart
  by a constant payload property or header, e.g. the `ce_type` of binary-mode CloudEvents), and a sender over
  `KafkaTemplate` per send operation. Request/reply operations with a reply channel use `ReplyingKafkaTemplate`, and
  replies carry the correlation id from the `correlationId` location. Topics, group and client ids (from the Kafka
  bindings) and servers go to `application.yaml`; message headers are merged with those of their traits as AsyncAPI
  does. Constraints Bean Validation can't express (draft-07 `dependencies`, `if`/`then`/`else`, tuples) become comments.
  Channels of other protocols are skipped with an info line, Avro payloads with a warning. Configured under
  `commands.generate.server_spring.asyncapi`; the design is ADR-102. The codegen conformance suite builds both
  perspectives at Level 2 and, at Level 3, has the application and the counterpart exchange the fixture's Kafka messages
  on an embedded broker (`@EmbeddedKafka`), including the `requestLabelRender` reply.
- `generate client go` generates a Go client for the `net/http` package of Go 1.22 from an OpenAPI 3.x document, using
  the standard library only. One `Client` over a configurable `*http.Client` takes functional options (base URL,
  request editors, user agent, an option per security scheme such as `WithAPIKey`), and has a method per operation and
  request media type taking a `context.Context` first. Each method returns a response struct with one typed field per
  documented status and media type (`JSON200`, `ApplicationProblemJSON404 *ProblemDetails`) and the raw
  `*http.Response`; statuses of 400 and above also return an `*APIError` with the RFC 9457 problem details.
  `text/event-stream` and `application/jsonl` responses are iterators typed from `itemSchema` (`x-itemSchema` in 3.0
  and 3.1), binary responses stay open as `io.ReadCloser`, multipart bodies are structs whose binary parts (from
  `contentMediaType` or `format: binary`) are `File` values honouring `encoding`, `content` parameters are sent as
  JSON, operation and path servers are honoured (`WithOperationServers(false)` ignores them), credentials go to the
  operations that accept them, and `x-internal` operations are left out. Types and validation are shared with
  `generate server go`. Configured under `commands.generate.client_go`.
- `generate client csharp` generates a C# client of an OpenAPI 3.0, 3.1 or 3.2 document for .NET 8 (or 9 and 10), built
  on `HttpClient` and `System.Text.Json`: a class library with one client per tag taking the `HttpClient` in its
  constructor (`client.Shipments.ListShipmentsAsync()`), a client of the whole API, and `Add{Api}Client()` registering
  them with `IHttpClientFactory`. Methods are `async` with a `CancellationToken`; they return the body of the success
  response, or a `*Result` by status when statuses have different bodies, and throw `ApiException` with the RFC 9457
  problem details of error responses. Every parameter style is supported, objects and `content` parameters (as JSON)
  included; bodies are JSON, text, binary, forms and multipart with `FilePart`s for `format: binary` and
  `contentMediaType` fields; other media types of bodies and responses are methods of their own
  (`UpdateShipmentJsonPatchAsync`); server-sent events and JSON Lines are `IAsyncEnumerable<T>` typed by `itemSchema`
  (or `x-itemSchema`). Operation and path servers are honoured, `x-internal` operations left out, and bearer, basic,
  OAuth 2.0, OpenID Connect and API key credentials sent by `DelegatingHandler`s. The models are those of
  `generate server aspnet`, with a source-generated `JsonSerializerContext` and converters that read every `oneOf`/
  `anyOf` with a discriminator wherever the discriminator is, falling back to `defaultMapping` (or
  `x-defaultMapping`). The code builds with `-warnaserror` and the .NET analyzers. Configured under
  `commands.generate.client_csharp`.
- The OpenAPI reader reads `itemSchema` of media types and `defaultMapping` of discriminators (OpenAPI 3.2), and the
  writer keeps them.
- `apigenie test import COLLECTION -o DIR` imports Collection Format v2.0/v2.1 JSON exports into
  folder-based `.http` tests with environments, bearer/basic/API-key references, upload assets,
  inherited scripts and a marker-gated QuickJS `pm` compatibility subset. Status-only tests become
  `??` assertions; unsupported script blocks are preserved as comments with source-line warnings,
  and OAuth 2 requests are disabled. `--spec` adds operation bindings and saved-response example
  overlays without editing the spec. `--environment` can be repeated; `--force` opts into replacing
  generated files. Authentication secrets are stored only in the generated environment file.
- `apigenie test` reads `QUERY` requests (the safe method with a body of OpenAPI 3.2) in `.http` files, and `--spec`
  takes OpenAPI 3.2 documents.
- `apigenie test` runs the requests of `.http` files (the httpYac flavour, which the JetBrains HTTP client and VS Code's
  REST Client read too) against a live server and validates every request and response against an OpenAPI document
  (`--spec`) with the checks of `apigenie-mock`'s validating proxy. Files have `###` regions, `{{var}}` variables,
  `@var = value` definitions, `# @name`/`# @ref`/`# @forceRef` chaining with `{{name.response.body.$.id}}`
  references, `{{ }}` scripts and JetBrains `> {% %}` handlers (QuickJS: `request`, `response`, `client`, `exports`,
  `test`, `assert`, `console`), `??` assertions, and `.env` and `http-client.env.json` environments (`--env`,
  `--env-file`, `--var`). Requests are bound to operations by method and path; `# @operation <operationId>` picks
  one, `# @operation off` skips the checks. `--generate` sends one request per operation, from the document's
  examples or generated values. The run fails with exit status 5 when a request fails or when the contract gate
  (`--fail-on`, `errors` by default, and `--min-coverage`) does; `--report` and `--report-junit` write
  `apigenie-mock`'s contract report with the requests added. Unknown directives are warnings. GraphQL, gRPC, HTTPS
  and OAuth 2 are not supported yet.
- `--strip-comments` for `format`, `overlay` and `lint --fix` drops the comments of the files they write, which
  they keep otherwise (ADR-093): YAML comments of OpenAPI, Swagger and AsyncAPI documents, comments of Protobuf
  files and `#` comments of GraphQL documents, whose descriptions are kept.
- `i18n apply` applies translations to Protobuf (`.proto`) and GraphQL (`.graphql`, `.graphqls`, `.gql`) files, keyed as
  `i18n extract` writes them: the leading comments of Protobuf declarations and the descriptions of GraphQL definitions
  are rewritten in place, in their style (`//` lines, `/* */` blocks, block or quoted strings), and every other byte of
  the file is kept, comments included, so applying untranslated texts returns the file unchanged. Keys addressing no
  comment or description are warnings, or errors with `--strict` (ADR-103).
- `i18n extract` extracts the texts of Swagger 2.0 documents, recognized by their `swagger` property, as it does for
  OpenAPI: titles, summaries and descriptions keyed by JSON pointers, which `i18n apply` puts back (ADR-103).
- `i18n apply --strip-comments` drops the YAML comments of a spec or the `#` comments of a GraphQL file (descriptions are
  kept), as `format`, `overlay` and `lint --fix` do (ADR-093); it is refused for Protobuf files, whose translated texts
  are comments.
- `i18n apply` applies translations to OpenAPI and AsyncAPI documents (JSON or YAML): each key of a translation file,
  a JSON pointer as `i18n extract` writes it, has the string it points to replaced by its value, and everything else
  is kept, YAML comments included. `--translations` can be repeated (later files override earlier ones), the result
  goes to `--output` or the standard output in the input format or that of `--format`, and keys pointing to nothing
  are warnings, or errors with `--strict`.
- `apigenie-mock --proxy-to ws://host:port` with an AsyncAPI document is a validating proxy for contract testing of a
  WebSocket API: clients of a WebSocket channel are relayed to the real server (handshake headers and subprotocol
  passed on, 502 or 504 when it can't be reached), and every message of both sides is checked against the channel's
  `receive` (client messages) and `send` (server messages) operations. Violations carry checks such as
  `message.incompatible` and `channel.send.undeclared`, go to the log, and `--strict` keeps invalid messages from going
  on (the client gets an `invalid-message` or `invalid-upstream-message` problem instead). Coverage counts each message
  of each operation; `--report`, `--report-junit`, `--fail-on`, `--min-coverage` and `GET /__apigenie/contract` work as
  for OpenAPI. HTTP channels and the MQTT broker keep being mocked. `contract.severity` accepts the new checks.
- `apigenie-mock --proxy-to ... --record-dir DIR` with an OpenAPI document writes each exchange the server answered as a
  stub file (`getPet-1.yaml`, or `GET_health-1.yaml` for a route of no operation: the request's method, path, query,
  headers and body, and the response's status, headers and body), which `--stubs DIR` (or `stubs:` in the
  configuration) replays without the server: before the document's examples, after `Prefer` and scenario rules, with
  `X-Apigenie-Mock-Source: stub:getPet-1`. `--record-har FILE` writes the whole session through the proxy, the mock's
  own answers included, as a HAR 1.2 file when the server stops, with `comment` (`proxy` or `mock`) and `_apigenie`
  (source, operation, upstream status, violations) on each entry. Both hide the values of `Authorization`, `Cookie`,
  `Set-Cookie`, `Proxy-Authorization` and `X-Api-Key`; `proxy.redact` sets the list. Also `proxy.record_har` and
  `APIGENIE_MOCK_RECORD_HAR`.
- `apigenie-mock --proxy-mode fallback` with an OpenAPI document and `--proxy-to`: every request still goes to the
  real server, but when the server can't be reached, doesn't answer in time, or answers 404 or 501 for an operation of
  the document, the mock answers as it would without `--proxy-to` (examples, generated data, scenarios, `Prefer`).
  Such answers carry `X-Apigenie-Mock-Upstream-Status`, are logged with `fallback: true` and aren't
  `response.status.unknown` violations. The contract report tells the server's answers from the mock's:
  `summary.sources`, each operation's `sources` and `mockedResponses`, two JUnit properties and a `Sources:` line in
  the summary. Configured under `proxy.mode`.
- `apigenie-mock` serves OpenAPI 3.2 documents: the `query` method and the methods of `additionalOperations` (such as
  `COPY`) are routed, validated and recorded in contract reports like the others. Streams described by `itemSchema` are
  answered with an empty body.
- A codegen conformance suite runs every OpenAPI generator on one shared, realistic OpenAPI 3.2 fixture, the Carpet
  Express Shipping API (`data/fixtures/openapi`, with its 3.1 and 3.0 variants, Spring and mock overlays and a feature
  catalog). Level 1, part of every ctest run, compares each generator's output byte for byte with a checked-in snapshot
  and checks a per-target manifest of the features it doesn't support yet. Levels 2 and 3 type-check and lint the output
  with the target's own toolchain and run the generated code against the fixture's contract (clients behind
  `apigenie-mock --proxy-to`, servers with `apigenie test --generate` and a hand-written request set), for the fetch,
  C#, Go, Java and Python clients and the FastAPI, Spring, Go, ASP.NET and Express servers, and the zod schemas at Level
  2, in a Linux workflow that runs on generator changes and on demand. The results are in `docs/codegen_conformance.md`;
  the design is ADR-098.
- The codegen conformance suite covers the AsyncAPI generators: `generate client ws` and `generate server ws` run on
  the Carpet Express Event Platform (`data/fixtures/asyncapi`), the AsyncAPI 3.0 event side of the same service (Kafka,
  WebSocket, MQTT 5, HTTP and AMQP channels, three request/reply styles, traits with a merge trap, bindings for all five
  protocols, draft-07 schemas), with a mock overlay and a feature catalog. Level 1 compares their output with
  snapshots and checks their manifests (the twelve non-WebSocket channels don't concern them; the reply of a
  request/reply operation is not generated yet). Level 2 type-checks and lints the generated packages; Level 3 drives
  the generated client and server through `apigenie-mock` as a validating WebSocket proxy. The matrix in
  `docs/codegen_conformance.md` has an AsyncAPI section; the design is ADR-100.
- `apigenie generate server faststream` generates a Python [FastStream](https://faststream.ag2.ai) application from the
  Kafka, AMQP (RabbitMQ) and MQTT channels of an AsyncAPI 3.x document: a broker per server (URL from an environment
  variable), a subscriber per receive operation (topics and patterns, consumer groups, queues, exchanges and routing
  keys, QoS from the bindings; several messages dispatched by a constant property) calling a handler you write in
  `handlers.py`, which regenerating keeps, and a publisher with a typed publish function per send operation. Payloads
  and headers become Pydantic v2 models, the same as `generate client python`'s, with trait headers merged; headers
  are typed `Header()` parameters. Requests wait for their reply on the document's reply channel by correlation id;
  reply addresses in headers become `reply_to` arguments. WebSocket and HTTP channels and Avro payloads are skipped
  and reported. Configuration is `commands.generate.server_faststream`; it is in the codegen conformance suite at
  Levels 1 to 3. The design is ADR-101.
- The codegen conformance suite runs `generate server faststream` at Level 3: the conformance workflow has RabbitMQ
  (with the fixture's virtual host) and Mosquitto service containers, pinned by digest, next to its Kafka one, and the
  generated application runs on the three brokers next to a counterpart. The counterpart publishes the fixture's
  examples (MQTT courier positions and sorter scans, AMQP customs decisions) to the application's handlers, receives
  what the application publishes (shipment events and label requests on Kafka, job offers on MQTT, customs filings on
  the `customs` exchange) and answers the label requests on their reply topic. The MQTT traffic goes through
  apigenie-mock's MQTT bridge, whose contract report checks it; the Kafka and AMQP messages and the MQTT 5 user
  properties are checked against the fixture in the harness (`checkMessages()`, ajv). Every item passes.
- `apigenie-mock --proxy-to http://host:port/graphql` with a GraphQL schema is a validating proxy for contract
  testing: GraphQL requests are checked against the schema (graphql-js's rules, variables, deprecated usage) and
  forwarded to the real server, whose answers are checked field by field against the schema and the request's selection
  set (missing and unexpected fields, nulls no error explains, scalar, enum and `__typename` values, lists, the shape of
  `errors`, statuses and media types). The proxy also introspects the server and reports where its schema differs
  (`schema.drift`, `schema.addition`). Violations carry checks such as `response.data.incompatible`, go to the log and
  `X-Apigenie-Mock-Violations-Detail`, and `--strict` answers bad requests itself and replaces bad answers (502). Field
  and root field coverage, `--report`, `--report-junit`, `--fail-on` and `--min-coverage` work as for OpenAPI.
  `--proxy-mode fallback` lets examples, scenarios and scripts answer first, and `--record-dir` writes the server's
  answers as examples the mock replays.
- `generate server fastapi` generates a Python FastAPI server from an OpenAPI 3.x document, with the project layout and
  options of openapi-generator's `python-fastapi` generator: pydantic 2 models (enums, unions with discriminators,
  recursive models, aliases and constraints), a router and a base class to implement per tag, security dependencies for
  API keys, HTTP, OAuth2 and OpenID Connect schemes with alternatives and scopes, `pyproject.toml`, a Dockerfile and
  pytest tests. Routes declare their status codes and response classes, parameters and bodies of every kind (forms,
  uploads, text, binary) are typed, and the implementation package, the tests and `.openapi-generator-ignore` are
  never overwritten. Configured under `commands.generate.server_fastapi`.
- `generate client python` generates a Python client of an OpenAPI document, built on httpx (or httpx2) and Pydantic 2:
  `Client` and `AsyncClient` classes with one resource per tag (`client.pets.list_pets()`), Pydantic models with
  Python field names, tagged unions for discriminators and `Input` variants for `readOnly`/`writeOnly` properties,
  all parameter styles, JSON, form, multipart, text and binary bodies, typed errors parsed with the documented schemas,
  retries with backoff honoring `Retry-After`, per-request options, raw and streaming responses, server-sent events,
  server variables, and authentication by security scheme, including the OAuth 2.0 client credentials flow. The code
  passes `mypy --strict`. Configured under `commands.generate.client_python`.
- `generate client java` generates a Java client of an OpenAPI document as a Maven project (Java 17, Spring Framework
  and Jackson versions from the Spring Boot BOM, without Spring Boot): an `ApiClient` on Spring's `RestClient`
  (`--library restclient`, the default) or `RestTemplate` (`resttemplate`) with one class per tag, whose operations have
  `op(...)`, `opWithHttpInfo(...)`, `opStream(...)` (a lazy `Stream` of `text/event-stream` and JSON Lines items) and
  `opWith<MediaType>(...)` methods for further request media types (`updateShipmentWithJsonPatch`); every parameter
  style, JSON-encoded `content` parameters, JSON, JSON Lines, form, multipart (`Resource` parts) and binary bodies,
  QUERY and other methods, operation and path servers, credentials per security scheme (bearer, basic, API keys in
  headers, queries and cookies) applied to the operations requiring them, and `ApiException`/`ProblemDetailsException`
  (RFC 9457) for errors; `x-internal` operations are left out. `--library feign` and `--library http-interface`
  generate Spring Cloud OpenFeign and Spring HTTP interface clients. Configured under `commands.generate.client_java`.
- `generate server express` generates an Express 5 server stub in TypeScript from OpenAPI 3.x documents: typed handler
  interfaces per tag, implemented in files of your own, and `createRouter(handlers, options)`, a router which checks
  security requirements with security handlers per scheme, decodes parameters in all OpenAPI styles and converts them
  to the types of their schemas, parses bodies, validates requests (and optionally responses) with Ajv or with
  generated validators without dependencies (`validation`), answers errors with RFC 9457 problem details and
  operations without handlers with 501. It can include the document and an example server. Configured under
  `commands.generate.server_express`.
- `generate server orpc` generates a TypeScript server based on oRPC (https://orpc.dev) from an OpenAPI document: Zod
  schemas, a procedure contract per operation with its route, input, output and type-safe errors (one per 4xx/5xx
  response, sent with the response body of the document), handler stubs, and a Node.js server serving the procedures
  with oRPC's `OpenAPIHandler` and their OpenAPI reference. Inputs use oRPC's compact structure unless the request
  needs the detailed one, parameters are converted from strings, and operations with several success responses or
  response headers return status, headers and body. Handlers and the server files are written once, so regenerating
  keeps them. Targets oRPC 1, or oRPC 2 (beta) with `orpc_version: 2`. Configured under
  `commands.generate.server_orpc`.
- `generate server aspnet` generates an ASP.NET Core server in C# built on Minimal APIs, for .NET 8 to 10 and
  without NuGet packages: records and enums of the schemas, one interface per group of operations whose methods return
  `Results<...>` unions of typed results (generated result types cover statuses `TypedResults` lacks), endpoints
  binding path, query, header and cookie parameters (array styles included) and JSON, text, binary, form and multipart
  bodies, and a project with `Program.cs` and stub implementations written only when missing. `oneOf` with a
  discriminator becomes `[JsonPolymorphic]` records, enums keep the values of the document, an endpoint filter
  validates requests against the constraints of their schemas (400 validation problems), and operations with security
  requirements call `RequireAuthorization()`. `layout: sources` writes only the sources, for existing projects.
  Configured under `commands.generate.server_aspnet`.
- `apigenie-mock --proxy-to http://host:port` with an OpenAPI document is a validating proxy for contract testing: it
  forwards every request to the real server and checks the request and the server's response against the document
  (parameters, bodies, security, statuses, media types, headers). Violations carry stable checks such as
  `response.body.incompatible` and show up in the log, in `X-Apigenie-Mock-Violations-Detail` and at
  `GET /__apigenie/contract`; `--strict` rejects bad requests (422) and replaces bad responses (502). The mock counts
  the operations, request bodies and responses the traffic covered, and writes `--report` (JSON) and `--report-junit`
  when it stops; `--fail-on` and `--min-coverage` make it exit with 5. Configured under `proxy` and `contract`.
- `overlay` command applies OpenAPI Overlays (versions 1.0, 1.1 and 1.2 of the specification) to an OpenAPI document,
  or to any JSON or YAML document: `apigenie overlay INPUT --overlay OVERLAY`, with `--overlay` repeated to apply
  several overlays in order. Updates, copies and removals follow the merge rules of the specification, reusable actions
  are supported, YAML comments are kept, and actions that select nothing are reported as warnings. `--validate` only
  checks the overlays, with the line and column of each issue. Targets are RFC 9535 JSONPath queries, functions
  (`length()`, `count()`, `match()`, `search()`, `value()`) included. The `openapi_overlay` WebAssembly module exports
  the same `apply` and `validate`.
- `generate server go` generates a Go server for the `net/http.ServeMux` of Go 1.22 from an OpenAPI 3.x document, using
  the standard library only. Names and layering follow oapi-codegen: `ServerInterface` receives bound parameters,
  `StrictServerInterface` request and response objects (typed headers, statuses, JSON, form, multipart, text and binary
  bodies). Types carry `Validate()` methods, and parameters and bodies are validated before the handlers run, with RFC
  9457 problem details for failures; `oneOf`/`anyOf` become structs with one field per variant, optional nullable
  properties `Nullable[T]`. Patterns end with `{$}` where needed, and the patterns `http.ServeMux` can't register together
  share one that dispatches to the most specific operation. A `SecurityHandler` and middlewares run before parameters
  are bound. Configured under `commands.generate.server_go`.
- `generate schema zod` generates Zod (v4) schemas, with their inferred TypeScript types, from the root schema and the
  `$defs` of a JSON Schema document (drafts 4 to 2020-12), or from the component schemas of an OpenAPI 3.x, Swagger 2.0
  or AsyncAPI document. Objects follow JSON Schema and keep unknown properties unless `additionalProperties` says
  otherwise; formats, numeric and string constraints, tuples, `patternProperties`, `not`, `if`/`then`/`else` and
  dependencies are validated, discriminated unions are detected, and recursive schemas become getters. Configured under
  `commands.generate.schema_zod`.
- `generate client ws` and `generate server ws` generate TypeScript code from the WebSocket channels of AsyncAPI 3.x
  documents: a client with one class per channel (browsers and Node.js, no dependencies) and a Node.js server built on
  the `ws` package, with session classes and handler interfaces. Payloads, address parameters and the query of the
  WebSocket binding are typed; received messages get handlers of their own when a property with a constant value tells
  them apart. The server implements the described application and the client its counterpart, unless the
  `perspective` option says otherwise. Configured under `commands.generate.client_ws` and `commands.generate.server_ws`.
- `format --check` reports the files that formatting would change, one path per line, and exits with 1 when
  there are any, without writing anything.
- GitHub Action (`src/github_action`, not published yet) that installs the CLI on Linux, macOS and Windows
  runners and runs `lint`, `format --check` or `diff` (against the pull request's base), with annotations on the
  files and a job summary. With `sarif: true`, lint issues are also uploaded to GitHub code scanning; on pull
  requests, the `diff` report is posted as a comment that later runs update in place.
- `sarif` formatter of `lint`: SARIF 2.1.0 for GitHub code scanning and other dashboards, with paths relative to the
  current directory and fingerprints based on JSON pointers, so that issues are tracked across runs.
- `apigenie-mock`, a mock server for OpenAPI 3.0 and 3.1 documents, installed with `apigenie` by every package and
  published as the `mykulyak/apigenie-mock` Docker image. It answers with the document's examples or with data
  generated from its schemas, validates requests (422 with problem details) and its own responses, checks security
  requirements, follows `Prefer` headers (`code`, `example`, `dynamic`, `delay`, `drop`, `scenario`), simulates
  latency, jitter, dropped connections and bandwidth limits, and logs every exchange as text or JSON lines. Scenarios
  force error states from a configuration file (`apigenie-mock.yaml` or `commands.mock`), `x-apigenie-mock` document
  extensions or an admin API under `/__apigenie`, which also reloads, reseeds and stops the server. `--watch` reloads
  the document and the configuration when they change. Schemas can pick faker functions with `x-faker`.
- `apigenie-mock` serves AsyncAPI 3.x documents: WebSocket clients of a channel get its send operations' messages on a
  schedule and their messages are checked against its receive operations and answered with their replies; HTTP
  channels take and answer messages; an in-house MQTT 3.1.1 and 5 broker serves the channels of mqtt servers.
- `apigenie-mock` serves the gRPC services of `.proto` files over cleartext HTTP/2, on the same port as HTTP:
  unary and streaming methods answered from YAML or JSON stub files (`--stubs`, `grpc.stubs`) with request and
  metadata matchers, templates, delays and error statuses with `google.rpc` details, or with messages generated from
  the response types. It honours deadlines and message limits, follows `x-apigenie-mock-*` metadata, applies
  scenarios (`grpc_status`, `grpc_message`) and scripts, serves server reflection (v1 and v1alpha) and health checks,
  proxies unanswered calls to an upstream server (`--proxy-to`) and records them as stub files (`--record-dir`). The
  admin API manages stubs and has the call history and a `verify` endpoint under `/__apigenie/grpc`. Imports are
  looked up in `--proto-path` directories and among the embedded well-known, `google/api` and `google/rpc` files.
- `apigenie-mock` also answers OpenAPI documents over cleartext HTTP/2 (prior knowledge).
- `apigenie-mock` serves GraphQL schemas (`.graphql`, `.graphqls`, `.gql`) at `/graphql`: GET, POST and batched
  requests per GraphQL over HTTP, validated against the schema with the rules and messages of graphql-js, executed
  with generated data (by type, field name and custom scalar name, or as graphql-faker's `@fake`, `@examples` and
  `@listLength` and the mock's `@mock` directives say), full introspection, GraphiQL and the SDL. Entities (types
  with an `id`) keep their values across requests, and `user(id:)`, `users`, `usersConnection` (Relay) and
  `createUser`, `updateUser`, `deleteUser`-like fields read and change them. Examples (`graphql.examples`, example
  files, `<schema>_examples/`) answer operations or fields, cut to the selection set and completed with generated
  values; scenario rules match operations and root fields and inject errors at field paths. Subscriptions are served
  over WebSocket (`graphql-transport-ws` and the legacy `graphql-ws`) and server-sent events. Configured under
  `graphql`.
- `apigenie-mock` runs JavaScript hooks (`--script`, `scripts`): `onRequest` answers requests, `onResponse` changes
  responses and their simulated delays or drops, `onMessage` changes or drops AsyncAPI messages, `onGraphQL`
  answers GraphQL operations, with state kept
  between requests, logging, seeded random numbers, faker functions and scenarios.
- Linter validates documents against the OpenAPI schema, and more rules support autofixing, including the new
  `schema-no-optional-nullable-properties` rule.
- `diff` command (openapi-diff) and the HTML documentation generator are available again.
- `diff` severities are configurable per context: `request` and `response` rule overlays (callbacks and webhooks
  swap them), `overrides` for single locations, conditions such as `if: required`, and `add_first_item` /
  `remove_last_item` rules. Schema properties are compared, respecting `readOnly` and `writeOnly`.
- `diff` detailed reports describe each change in all formats.
- `diff` command compares AsyncAPI 3.x documents: servers, channels, operations, messages and their payloads and
  headers, security schemes, bindings (property by property for HTTP, WebSockets, Kafka, AMQP and MQTT) and
  components, with the same reports, formatters, exit status and `--update-version` as OpenAPI documents. The
  severity of a message change depends on whether the application sends or receives the message (`send` and
  `receive` rule overlays). Configured under `commands.diff.asyncapi`.
- `diff` command compares Protobuf (proto3 `.proto`) files: package, imports, options, messages, fields (matched by
  their numbers), oneofs, enums, services, methods, extend blocks, reserved numbers and names, and comments, with the
  same reports, formatters and exit status as OpenAPI documents. Type names are resolved before they are compared,
  and removing a field whose number the new file reserves is not breaking. Severities can depend on `reserved`,
  `deprecated` and `wire_compatible` conditions, and options are configured by their names. Configured under
  `commands.diff.protobuf`.
- `diff` command compares Swagger 2.0 documents: host, base path, schemes, media types, paths, operations,
  parameters (matched by location and name, the body parameter by location), responses, headers, schemas
  (following references to definitions), security definitions and requirements, and tags, with the same reports,
  formatters, exit status and `--update-version` as OpenAPI documents. Body parameters and consumed media types get
  the `request` rules, responses and produced media types the `response` ones, and definitions the stricter of the
  two. Configured under `commands.diff.swagger`.
- `diff` command compares GraphQL schemas (`.graphql`, `.graphqls` and `.gql` files): root operation types, types of
  every kind, fields, arguments, input fields, default values, interfaces, union members, enum values, directive
  definitions, applied directives and descriptions, with the same reports, formatters and exit status as OpenAPI
  documents. Type extensions are merged into their types, and operations are ignored. Severities follow graphql-js's
  breaking changes and can depend on `required`, `compatible`, `deprecated` and boolean conditions; directives are
  configured by their names. Configured under `commands.diff.graphql`.
- `changelog` command builds the changelog of an OpenAPI file from its git history: one entry per commit or per
  release tag, or the history of each operation (`--by operation`, filtered with `--operation`), as stylish text,
  Markdown, HTML or JSON. Files the specification references are followed in each version.
- `changelog` command builds the changelog of AsyncAPI 3.x files too: added, removed and changed operations, channels
  and servers, with the changes of a channel's messages shown under the operations using it, rated with the
  `commands.diff.asyncapi` rules. `--operation` selects AsyncAPI operations by id, by `send`/`receive` and channel
  address, or by channel address.
- `changelog` command builds the changelog of Protobuf (`.proto`) files too: added, removed and changed methods
  (named `Service.Method`), messages, enums, services and extensions, package changes shown like version changes,
  rated with the `commands.diff.protobuf` rules. The file is compared on its own, without the files it imports.
  `--by operation` groups the changes by method, and `--operation` selects methods by full name, method name or
  service name.
- Swagger 2.0 input support.
- `changelog` command builds the changelog of Swagger 2.0 documents too: added, removed, deprecated and changed
  operations, with the changes of a path item shown under its operations, and the host, base path, schemes, media
  types and security of the API as metadata, rated with the `commands.diff.swagger` rules. Files the specification
  references are followed in each version.
- `changelog` command builds the changelog of GraphQL (`.graphql`, `.graphqls`, `.gql`) schema files too: added,
  removed and changed operations (the fields of the root operation types, named like `Query.books`), scalars, object
  types, interfaces, unions, enums, input objects and directive definitions, with changes of the root operation
  types, the schema description and the schema directives as metadata, rated with the `commands.diff.graphql` rules.
  The file is compared on its own. `--by operation` groups the changes by operation, and `--operation` selects
  operations by full name, field name, root type name or operation type (`query`, `mutation`, `subscription`).
- `bundle` command bundles Swagger 2.0 documents and the local files they reference into a single file: referenced
  schemas, parameters and responses become entries of `definitions`, `parameters` and `responses`, and referenced
  path items take the content of their files.
- `bundle` command bundles AsyncAPI 3.x documents and the local files they reference into a single file. Root
  servers, channels and operations kept in other files take the content of those files, so that operations still
  refer to their channels and channel messages; other referenced objects become components. Schemas in other formats,
  such as Avro, are copied as they are, and references by URL are kept.
- `bundle` command bundles Protobuf (`.proto`) files: the input file and the messages, enums and extensions it uses
  from the files it imports (searched in the `-I`/`--proto-path` directories) are combined into one proto3 file.
  Declarations from other packages are renamed with a prefix made from their package, and well-known type imports
  are kept.
- `format` command formats AsyncAPI 3.x documents, configured under `commands.format.asyncapi`.
- `i18n` command extracts the texts of AsyncAPI 3.x documents for translation: the titles, summaries and
  descriptions of servers, channels, operations, messages, schemas and the other objects, keyed by their JSON
  pointers.
- `i18n` command extracts the leading comments of Protobuf (`.proto`) files for translation, keyed by the fully
  qualified name of the message, field, oneof, enum, enum value, service or method they document; enum values are
  keyed under their enum, and the comment of the file (that of its `syntax` statement) under the package name.
- `i18n` command extracts the descriptions of GraphQL (`.graphql`, `.graphqls`, `.gql`) files for translation, keyed
  by full name: the schema (`schema`), types, fields, arguments, input fields, enum values and directives by their
  schema coordinates (e.g. `Query.search(text:)`, `Genre.POETRY`, `@key`), operations and their variables (e.g.
  `query FindBooks`, `query FindBooks($text:)`) and fragments (e.g. `fragment BookSummary`).
- `format` command formats Swagger 2.0 documents, configured under `commands.format.swagger`.
- `format` command formats GraphQL schemas and operations (`.graphql`, `.graphqls`, `.gql`) in the layout of Prettier,
  keeping all comments, and optionally sorts definitions and the members of types. Configured under
  `commands.format.graphql`.
- `lint` command lints AsyncAPI 3.x documents with 31 rules (ported from the OpenAPI ones where they apply, plus
  `channel-parameters-defined`, `channel-addresses-unique` and `server-hosts`), rulesets, custom rules and autofixes,
  configured under `commands.lint.asyncapi`.
- `lint` command lints Swagger 2.0 documents with 46 rules (ported from the OpenAPI ones where they apply, plus
  `host-defined`, `schemes-secure`, `media-types-defined` and `swagger-validation`, which reports the specification
  violations found by the Swagger validator), rulesets, custom rules and autofixes, configured under
  `commands.lint.swagger`.
- `lint` command lints Protobuf (proto3 `.proto`) files with 39 rules modelled on buf's: naming conventions, packages
  (versions, directories, consistent language options, import cycles between packages), imports (unresolved,
  unused, public, weak, cycles, order), enums, services and RPCs, comments and spell checking. Imports are looked up
  in `--proto-path` directories, the `import_paths` of the configuration and the directories above the file, with
  the well-known `google/protobuf` files built in. `--fix` removes unused imports and sorts imports; an
  `// apigenie-lint-disable <rules>` comment disables rules for a declaration. Configured under
  `commands.lint.protobuf` with the `recommended` (default), `strict` and `all` rulesets.
- `lint` command lints GraphQL schemas and operations (`.graphql`, `.graphqls`, `.gql`) with 87 rules modelled on
  graphql-eslint, graphql-schema-linter and Apollo's schema linter: the type system and operation rules of the
  specification, naming conventions, descriptions, deprecations (reasons, deletion dates), schema design (root types,
  mutations and payloads, unreachable types, identifiers, `@oneOf`, circular input types), the Relay connection
  conventions, ordering, spelling, and operations checked against the schema (unknown fields, types and arguments,
  required arguments, deprecated fields, selection depth, identifier selections). Operations are checked against the
  files named by `--graphql-schema` or by the `schema` option, or against the type system of their own document. A `# apigenie-lint-disable <rules>`
  comment disables rules for a definition. Configured under `commands.lint.graphql` with the `recommended` (default),
  `strict`, `all` and `relay` rulesets; `--fix` doesn't apply to GraphQL files.
- Minimal telemetry.
- Linter rules reasoning about schemas: `schema-no-contradictions` (constraints rejecting every value, and
  properties forbidden by an `allOf` member with `additionalProperties: false`), `schema-oneof-no-overlap` (`oneOf`
  branches a single value matches, shown in the report), `schema-required-properties-defined` and
  `schema-conditional-effective` (`if`/`then`/`else` without effect), all in the `recommended` ruleset, and
  `patch-request-body-partial` (required properties in `PATCH` bodies) in the `strict` ruleset.
- Official release binaries for macOS (arm64), Linux (x64, static, runs on any distribution) and Windows (x64),
  plus `.deb` and `.rpm` packages, a Homebrew formula, per-platform npm packages and a versioned Docker image.
- `generate server express` and `generate client fetch` follow `discriminator.defaultMapping` (OpenAPI 3.2;
  `x-defaultMapping` in 3.0 and 3.1). Express validates such a `oneOf` by the discriminating property: with Ajv as an
  `if`/`then`/`else` chain that ends with the default schema, with `validation: generated` by a dispatch reporting the
  same issues. A value whose property matches no mapping, or lacks it, is validated against the default schema instead
  of failing `oneOf`. The types of both targets get a type guard per member (`isParcelShipment(value: Shipment)`), the
  default member's taking the values no mapping matches. The fetch client's conformance snapshots cover OpenAPI 3.1 and
  3.0 too.

### Changed

- The documentation smoke run of the codegen conformance suite is `generate docs` (`test_docs_bundle`) instead of
  `generate doc html`, and the `e2e/generate_doc_html` benchmark cases are `e2e/generate_docs`.
- `apigenie test import` writes the credentials it finds (bearer tokens, basic credentials, API keys, OAuth 2 client
  secrets and passwords) to a generated `http-client.private.env.json` instead of `http-client.env.json`, which keeps
  the other variables and no secret; `apigenie test` reads both. The `sensitive-environment` warning names the private
  file.
- The web components read AsyncAPI documents with the `asyncapi` WebAssembly module, as they read GraphQL and
  Protobuf: set `asyncapi-wasm-url` on `<apg-spec>` or `<apg-api-reference>`, or call `configureAsyncApiEngine(url)`.
  `npm run prerender` takes `--asyncapi-wasm`. There is no JavaScript reader for AsyncAPI any more; without the module,
  AsyncAPI documents fail to load with a message saying what to set. The views are unchanged.
  `@mykulyak/apigenie-asyncapi-view` reads the module's documentation model; its `parse` and `traits` modules are
  gone. Server-rendered pages embed the model, so hydration needs no module.
- The JSON contract reports of `apigenie-mock --report`, `GET /__apigenie/contract` and `apigenie test --report` give
  each OpenAPI operation the JSON `pointer` of the operation in the document (e.g. `/paths/~1pets/get`).
- Internal: `swagger_convert` returns a source map with each conversion, from the JSON pointers of the result to those
  of the Swagger 2.0 document.
- `apigenie-mock --proxy-to` with a `.proto` file logs request violations instead of failing the call with
  INVALID_ARGUMENT, as the OpenAPI, GraphQL and AsyncAPI proxies do; `--strict` or `grpc.validation.request: enforce`
  restores it, and a request is then checked before it reaches the upstream (an always-mode proxy forwarded it first).
  A mock without `--proxy-to` keeps enforcing requests, and now also rejects a request that misses a field marked
  `[(google.api.field_behavior) = REQUIRED]`. A non-200 HTTP answer of the upstream ends the call with the
  status gRPC clients make of it (UNAVAILABLE for 503) instead of always UNAVAILABLE, and an upstream answer without
  `grpc-status` ends as UNKNOWN instead of OK.
- `--report` and `--report-junit` of `apigenie-mock` are accepted for `.proto` files, and `/__apigenie/contract`
  answers for them.
- The requester of `generate server aspnet`'s Kafka code (AsyncAPI) waits for replies on the runtime's new
  `KafkaReplies`, which `generate client csharp` shares; its behaviour is unchanged. The OpenAPI configurations of
  `generate client csharp` and `generate server aspnet` ignore their `asyncapi` section instead of rejecting it as an
  unknown option.

- `generate server aspnet` (OpenAPI) writes the recursive DataAnnotations validation of `ValidationFilter` as
  `Infrastructure/ModelValidator.cs`, which the AsyncAPI Kafka application uses for its messages too; the behavior
  is unchanged.
- `apigenie` and `apigenie-mock` link Mbed TLS 3.6 (Apache-2.0), the first runtime library from vcpkg; `credits` and
  `license --library mbedtls` list it. The release binaries grow by about 0.9 MB (macOS arm64: `apigenie` +3.5%,
  `apigenie-mock` +8.2%). The Docker images now include Alpine's CA certificates.
- `apigenie-mock --proxy-to` no longer refuses `https://` and `wss://` targets with exit status 2, and the 426 answer
  to gRPC over HTTP/1.1 on a TLS port says to ask for `h2` by ALPN instead of offering `Upgrade: h2c`.
- `generate server spring` is built on `openapi_generator_java`, the Java layer it shares with `generate client java`,
  whose Feign and HTTP interface writers now generate its `spring-cloud` and `spring-http-interface` libraries; their
  output is unchanged. Models get `defaultImpl` from `discriminator.defaultMapping` (`x-defaultMapping` before 3.2),
  name implicit discriminator mappings after the `const` value of the members (`person` instead of `Person`), no
  longer require the properties of `anyOf`/`oneOf` alternatives (Person and Company required both `email` and `phone`
  of ContactChannels), and treat an `allOf` with only a reference to a `oneOf` interface as that interface (3.0
  documents produced a class extending an interface).
- `generate server go`: an `anyOf` or `oneOf` whose members only list required properties no longer makes a union of
  untyped values, so `allOf` schemas holding one are merged into structs (instead of `any`) and `Validate()` checks
  the alternatives; a discriminator's `defaultMapping` (`x-defaultMapping` in 3.0 and 3.1) decodes unknown values as
  its fallback variant, and an implicit mapping also accepts the `const` the variant gives the property. The runtime's
  request binders moved from `runtime_params.gen.go` to a new `runtime_bind.gen.go`.
- The OpenAPI library reads a media type's `itemSchema` and a discriminator's `defaultMapping` (3.2), and their
  `x-itemSchema` and `x-defaultMapping` forms in 3.0 and 3.1 documents.
- `generate server aspnet` and `generate client csharp` share their C# models (`src/openapi_generator_csharp`). The
  server's output changes in two ways: the implicit discriminator value of a `oneOf` variant is the `const` of its
  discriminator property when it has one (e.g. `"person"` instead of the schema name `"Person"`), and a `oneOf` or
  `anyOf` whose members map to one C# type has that type (e.g. `List<string>` for strings of the `ipv4` and `ipv6`
  formats, instead of `List<object>`).
- The contract report of `apigenie-mock` (gate, JSON and JUnit) moved into the `mock` and `openapi_mock` libraries,
  shared with `apigenie test`; its output is unchanged.
- `format` keeps the YAML comments of OpenAPI, Swagger and AsyncAPI documents (at the top and the end of the file,
  above keys, at the end of lines, inside sequences and between entries); comments move with their keys when
  properties are sorted. Before, every comment was dropped, and `format --check` reported commented files that were
  formatted.
- `lint --fix` keeps the YAML comments of the OpenAPI, Swagger and AsyncAPI documents it rewrites, including those of
  the properties a fix replaces, instead of dropping them all.
- `format` writes a Protobuf comment that follows a declaration on the next line (and that protoc attaches to it)
  on its own line again, instead of moving it to the end of the declaration's line.
- `i18n` has two subcommands: `i18n extract` extracts texts, as `i18n` did, and `i18n apply` applies translations.
  `apigenie i18n FILE --output DEST` becomes `apigenie i18n extract FILE --output DEST`, which also accepts `-o`.
- `apigenie-mock --stubs` with a GraphQL schema or an AsyncAPI document exits with status 2 instead of being ignored;
  stubs answer the calls of a `.proto` file and, now, the operations of an OpenAPI document.
- `lint` exits with status 1 when it reports issues of severity `error` (those remaining after `--fix`), so CI
  jobs fail on them; warnings keep the exit status at 0.
- The CLI binary is about 2.8 MB (14%) smaller: the test-data generator's string tables (names, addresses, words and
  the like) are stored compressed and decoded when first used, instead of as pointer tables.
- The built-in English spelling dictionary is stored compressed (about 290 KB less in the binary) and decoded
  only when the first spell-check rule runs; the decoded bytes are released once the dictionary is parsed.
- The third-party license texts shown by `license --library` are stored compressed and decoded only when one is
  printed.
- `format` reports files that are neither OpenAPI nor AsyncAPI documents and leaves them untouched,
  instead of writing empty output.
- Parse errors in JSON and YAML input now report why and where the input cannot be parsed.
- `lint` with several input files writes a single report for the `json`, `checkstyle`, `junit`, `html`, `sarif` and
  `tap` formatters, instead of one document per file.
- `diff` exit status and `--update-version` consider all changes, whatever the report shows, and a fixed severity
  of a node caps the severities of changes inside it (e.g. adding an optional parameter is non-breaking).
- `diff --update-version` changes only the version in the file, keeping its formatting.
- `diff` configuration is validated: unknown node types, properties and severities are reported.
- `generate server spring` builds Java sources with a syntax tree instead of text templates. The generated code
  is the same, but imports are sorted and blank lines and indentation are consistent.
- `unused-shared-component` is enabled again in the `recommended` (warning), `strict` and `all` rulesets, and skips
  documents without operations, which are libraries of components for other documents.
- `schema-no-optional-nullable-properties` recognizes OpenAPI 3.0 `nullable: true`, referenced nullable schemas and
  `anyOf`/`oneOf` null branches, finds `required` in `allOf` members, and skips `PATCH` and merge-patch bodies, where
  `null` clears a value (option `ignorePatchBodies`).
- `spell-check` (OpenAPI and AsyncAPI) now checks spelling: it reports each misspelled word of titles, summaries
  and descriptions with suggested corrections, using a built-in English dictionary, and skips code, URLs,
  identifiers and acronyms. Options `words` (extra words), `suggestions` and `dictionary`/`affix` (any Hunspell
  dictionary) are optional. The rule moved from the `recommended` ruleset to `strict` and `all`.
- Internal: the Swagger 2.0 to OpenAPI 3.2 conversion behind `convert --to openapi32` moved from the CLI into its own
  library, `swagger_convert`, which also reports what each conversion approximates or drops (not shown by the CLI
  yet). The output of `convert` is unchanged.
- Internal: a release gate (`release_gate.yaml`) runs every test on Linux, Windows and macOS, the tests that build
  generated code with Java, Go, .NET and Python, the RealWorld demo, codegen conformance Levels 2 and 3 and the
  WebAssembly build; a `cli-*` tag only gets its draft release once the gate passed on the tagged commit.

### Removed

- `generate doc html`, the Astro documentation project it generated and the `@mykulyak/api-genie-doc-html-template`
  package it depended on, with the `commands.generate.doc_html` configuration section (see Upgrading). Internal:
  `openapi_generator_doc_html` and `code_morph_astro`.

### Fixed

- `apigenie-mock --license` without a library name prints API Genie's license instead of the usage: an option whose
  value is optional counted as given only with a value.
- `generate server spring` reads request bodies typed by a oneOf without discriminator (JSON Patch operations, Carpet
  Express's recursive `SearchFilter`): such interfaces had no type information, so Jackson couldn't instantiate them
  and the request answered 500. The interface now names a `Deserializer` built on the generated `OneOfDeserializer`,
  which reads the one member the value matches: a member that declares all its properties (or takes additional
  properties), reads it and, with Bean Validation, is valid. A value matching no member, or several, is a 400.
  `useDeductionForOneOfInterfaces=true` keeps Jackson's deduction. Strings with `format: uri` (`java.net.URI`) no
  longer get `@Pattern` or `@Size` in `generate server spring` and `generate client java`: Bean Validation can't check
  them on a URI and threw `UnexpectedTypeException` (the server's `createWebhookSubscription` answered 500); their
  pattern isn't checked.
- The Pydantic models of `generate client python`, `generate server faststream` and the Python Kafka client check
  `pattern`: `Annotated[str, matching(r"...")]`, a validator of `_models.py` compiling the pattern with Python's `re`
  when a value is first checked (Pydantic's default engine rejects look-arounds, back-references and large `\w`
  repetitions, which would break the model). Named string schemas keep their constraints in their aliases, e.g.
  `ShipmentId: TypeAlias = Annotated[str, matching(r"^shp_[0-9A-Za-z]{24}$")]`; a pattern `re` can't compile, such as
  one using `\p{L}`, isn't checked.
- `generate server faststream`: published messages and replies no longer carry `null` for optional fields that weren't
  set, which their schemas don't allow. The publish functions and the subscribers' replies send payloads through the
  runtime's new `encode_message()` (the fields that were set), instead of letting FastStream serialize the models with
  every field. Subscribers of operations with a static reply channel now return a `KafkaResponse`, `RabbitResponse` or
  `MQTTResponse`, and their reply publisher states the reply's schema (`schema=`).
- The code of `generate client ws` and `generate server ws` passes typescript-eslint's recommended type-checked rules:
  options and handler interfaces that would be empty are type aliases, the client runtime's
  `WebSocketLike.addEventListener` has one overload per event instead of an `any` listener, and the shared AsyncAPI type
  mapper no longer writes `unknown` into unions (`[key: string]: unknown`) or intersections (an `anyOf` of `required`
  lists).
- The validators of `generate server express` (`validation: functions`) import `pointerToken` only when a generated
  function uses it, so object schemas with `additionalProperties: true` no longer leave an unused import.
- Generated values (`apigenie-mock` responses and messages, examples) satisfy an object schema's `oneOf`/`anyOf` next
  to its `properties`, such as `anyOf: [{required: [phone]}, {required: [email]}]`: one alternative is picked and
  what it requires is generated. The alternatives used to be ignored, so such objects could lack every property they
  ask for.
- `apigenie-mock`: the problems of an `x-apigenie-mock` extension name it by a well-formed JSON pointer
  (`/paths/~1pets/get/x-apigenie-mock`, not `/paths//pets/get/...`), and by its line when the value has no position
  of its own.
- `apigenie-mock` generates AsyncAPI messages whose schemas use AsyncAPI's string `discriminator` or an `externalDocs`
  given by `$ref`: such documents made every message without an example fail with "the payload has no schema values
  can be generated from". A reply whose message has its `correlationId` in the payload now carries the request's value
  (Carpet Express's `requestPickup` gets a `pickupConfirmed` with its `requestId`).
- `apigenie-mock --proxy-to ws://` checks the server's reply to a client message of a request/reply operation against
  the reply's messages and its `correlationId` (`message.reply.uncorrelated`), instead of reporting it as
  `channel.send.undeclared` on a channel without `send` operations (ADR-110).
- `generate server faststream` no longer fails with "The message schemas can't be mapped to Python types" when a payload
  schema's `externalDocs` is a `$ref`, as the AsyncAPI fixture's `CloudEvent` has: the reference is followed.
- The AsyncAPI contract report counts the requests of HTTP channels, mocked or proxied, as messages of their
  operations.
- `generate client csharp`: the generated project compiles again: the client of the API is registered with
  `AddHttpClient<TClient, TClient>(factory)`, as `AddHttpClient<TClient>` has no factory overload and bound the lambda to
  its configuration callback (CS1503). Unions read by the generated discriminator converters no longer carry
  `[JsonPolymorphic]`/`[JsonDerivedType]`, which System.Text.Json rejects next to a custom converter ("does not support
  metadata writes or reads") when sending or reading a `oneOf` with a discriminator.
- `generate client csharp` and `generate server aspnet`: properties with a default value are settable instead of
  init-only, because the System.Text.Json source generator of .NET 8 assigns every init-only property and replaced the
  default of an absent one with `0`/`false`/`null`; decimals described as strings (`type: string, format: decimal`) are
  written as JSON strings.
- `generate client python`: form body fields whose `encoding` sets `style` or `explode` are written like query parameters
  of that style (`deepObject`: `hints[building]=rear`) instead of as JSON text. The package passes ruff's default rules:
  `__all__` lists are sorted as RUF022 expects, and the runtime uses `X | Y` unions and `Self`.
- `generate server express` with `validation: generated`: objects without declared properties (maps), or with only
  `patternProperties`, no longer get validators with constant conditions (`if (!(false))`, `false || ...`), which
  failed ESLint's `no-constant-condition`. The codegen conformance suite's Level 2 now also type-checks and lints a
  `validation: generated` build.
- `generate client fetch`: properties of `application/x-www-form-urlencoded` bodies whose `encoding` sets `style` or
  `explode` are written like query parameters of that style (`deepObject`: `hints%5Bbuilding%5D=rear`, also
  `pipeDelimited`, `spaceDelimited` and unexploded `form`) instead of as JSON text; the other object properties stay
  JSON. The runtime no longer calls `String()` on values of unknown type, so it passes typescript-eslint's
  `no-base-to-string`.
- `generate server express` routes `QUERY` and `COPY` operations (OpenAPI 3.2): their routes were typed with a method
  the runtime's `HttpMethod` type lacked, so the generated package didn't compile. An empty form field of a nullable
  property (`location=` for `oneOf: [GeoPoint, {type: null}]`) is read as null instead of failing validation, and the
  runtime passes typescript-eslint's recommended type-checked rules.
- `generate client fetch`, `generate server express` and `generate server orpc`: `anyOf`/`oneOf` alternatives that only
  add constraints (`anyOf: [{required: [email]}, {required: [phone]}]`) no longer add `& unknown` to the type.
- `generate server aspnet`: an empty form field for an object (`location=`, how form style writes an empty or null
  value) is read as null instead of failing to parse as JSON with 400.
- `generate server spring`: a `@lombok.*` annotation in a model's `x-class-extra-annotation` drops the members Lombok
  generates for that model and adds Lombok to the pom, as `additionalModelTypeAnnotations` does; before, the model kept
  its own `equals`/`hashCode` next to `@lombok.EqualsAndHashCode` and the project didn't build without Lombok. Deprecated
  parameters no longer get `@Deprecated`, which has no effect on parameters (`javac -Xlint` warns since JDK 21); the
  deprecation stays in `@Parameter(deprecated = true)`.
- `generate client python` and `generate server faststream`: `allOf` parts with `oneOf`/`anyOf` alternatives that only
  add constraints, such as Carpet Express's `ContactChannels` (an email or a phone), are merged like other object
  parts, so `Person` and `Company` are models instead of `Any`. Discriminated unions dispatch on the mapping, on the
  schema names of the members it leaves out (the implicit mapping) and on the value each of those members fixes the
  property to with `const` or a single `enum` value (`partyType: person` of a schema named `Person`). Values whose tag
  is missing or unknown are read as the `discriminator.defaultMapping` schema (`x-defaultMapping` in OpenAPI 3.0 and
  3.1), which joins the union if it isn't a member; before, they matched no model. The unions keep their callable
  `pydantic.Discriminator`, as `Field(discriminator=...)` can neither fall back nor take several tags per model. The
  codegen conformance suite checks `generate client python` against the OpenAPI 3.1 and 3.0 fixtures too.
- `generate server fastapi` passes the codegen conformance suite's mypy, ruff and runtime checks without known
  failures, on the OpenAPI 3.2, 3.1 and 3.0 fixtures:
  - Discriminator tags follow the Python models: a member that fixes the property with `const` or a single `enum`
    value gets that value (`party_type: Literal["person"]` for a schema named `Person`), where the implicit mapping
    made it `Literal["Person"]` and rejected valid parties. A union with a `discriminator.defaultMapping`
    (`x-defaultMapping` in OpenAPI 3.0 and 3.1) dispatches with a callable `Discriminator()` that reads values with a
    missing or unknown tag as the default schema, which joins the union if it isn't a member.
  - `RootModel` subclasses have their type argument (`RootModel[int | str]`; a forward reference in a cycle), which
    `mypy --strict` asked for.
  - A request body with several JSON media types, such as `application/merge-patch+json` and
    `application/json-patch+json`, is validated against the schema of the request's `Content-Type` (415 for another
    one); the route took only the first media type's schema. The body parameter is the union of the schemas and the
    served OpenAPI document lists every media type.
  - Integer enums in parameters and form fields convert the request's text (`dpi=300`); `Literal[203, 300, 600]`
    rejected every value.
  - Multipart file parts described with `contentMediaType` or `contentEncoding: binary` (OpenAPI 3.1 and 3.2), not
    only `format: binary`, are `UploadFile`s, and arrays of them `list[UploadFile]`.
  - Imports are sorted the way Ruff's isort rules expect (case-insensitive, numbers by value, long single-name imports
    wrapped), and the imports at the end of modules of a cycle no longer carry a `# noqa: E402` that Ruff reports as
    unused.
- `apigenie test --generate` sends multipart file parts (`format: binary`, `contentMediaType` or
  `contentEncoding: binary`) with a file name and the Content-Type of their encoding, and an array as a part per item;
  servers that only take parts with a file name as files, such as FastAPI's and ASP.NET Core's, rejected the generated
  requests.
- `generate client python` and `generate server faststream`: an object schema with properties of its own and `oneOf`
  or `anyOf` alternatives that are objects (each narrowing a property or requiring others) becomes a union of one
  model per alternative with the object's properties merged in. The properties were lost (a union of classes holding
  only the alternatives' properties), and `anyOf` of `required` lists, such as "an email or a phone", was `Any`.
- The CLI no longer writes `.apigenie.telemetry` in the current directory; set
  `APIGENIE_TELEMETRY_FILE` to keep a local telemetry log.
- `apigenie-mock` and `apigenie test` type the fields of form and multipart bodies (and deepObject and delimited
  parameters) whose properties come from `allOf` members, references included: `residential=false` of a body
  `allOf: [$ref Address, {...}]` is the boolean `false`, not the string. They were validated as strings, so valid
  requests were reported or rejected with 422.
- YAML output quotes strings that YAML 1.1 parsers (PyYAML, SnakeYAML, go-yaml v2) read as booleans, numbers or
  merge keys: `yes`, `No`, `ON`, `off`, `y`, `N`, `0b101`, `1_000`, `1:30`, `<<` and the like. Before, `bundle`,
  `overlay`, `lint --fix`, `convert` and `format` with the `best-fit` style wrote them plain, so other tools read
  `enum: [yes, no]` as booleans and `1:30` as 90.
- `apigenie-mock` validates requests and responses whose schemas refer to themselves (trees, nested filters, recursive
  `oneOf`s). They were accepted without any check, in OpenAPI and AsyncAPI documents alike. The lint rules
  `schema-no-contradictions` and `schema-oneof-no-overlap` now analyze such schemas too.
- OpenAPI 3.2 documents: examples written with `dataValue` and media types that refer to `components/mediaTypes` are
  read. Generators no longer drop them (Spring rendered such examples as `null`, Go typed such problem responses as
  `any`), and `apigenie-mock` answers with those examples.
- `generate server fastapi` routes the OpenAPI 3.2 `query` method and the methods of `additionalOperations` (such as
  `COPY`) with `@router.api_route(..., methods=[...])`. They were emitted as `@router.query`/`@router.copy`, which
  `APIRouter` doesn't have, so a server generated from a document with such an operation failed to import.
- `convert --to openapi32` converts the structure of Swagger 2.0 documents, not only their references: body and
  `formData` parameters become request bodies with the media types of `consumes` (files as `multipart/form-data`),
  `collectionFormat` becomes `style` and `explode`, response schemas, headers and examples move into `content` per media
  type of `produces`, global body parameters become `components.requestBodies`, and references to parameters and
  responses point into `components`. Schemas get `type: file` as binary strings, object discriminators, numeric
  exclusive bounds and `x-nullable` as a `null` type. Before, most converted documents could not be read (2163 of the
  2168 Swagger documents of the openapi-directory corpus convert into readable documents now, the others are invalid).
- Many memory-safety and robustness issues in the parsers, bundler, reader and linter.
- `diff` changelog reports rate added, removed and modified operations by their own changes rather than their
  path's, report request body changes as such instead of as response codes, and no longer list a removed
  deprecated operation as deprecated.
- `generate server spring` numbers enum constants whose names collide (e.g. the values `+1` and `-1`, both named
  `_1`), like openapi-generator, so the generated models compile.
- `test` reports a rejected certificate as such for `wss://`, `mqtts://` and `grpcs://` URLs whose host name has
  several addresses: it stops at the first address that answers instead of trying the others and reporting the
  last one's "Connection refused" (on macOS, `localhost` is 127.0.0.1 and ::1, and a server often listens on one).
- The YAML and JSON writers report an alias of a collection that contains it as soon as they meet it again,
  instead of after expanding it to the depth limit, which overflowed the JavaScript stack of the WebAssembly
  build.
- `generate server spring` with `useSpringBoot4` no longer declares `spring-boot-starter-restclient` (or
  `-webclient`) twice, which Maven rejects as a duplicate dependency.

## 0.8.2 (2025-11-13)

Pre-release, published on [GitHub](https://github.com/mykulyak/api-genie/releases/tag/cli-0.8.2).

## 0.8.0 (2025-07-12)

Pre-release, published on [GitHub](https://github.com/mykulyak/api-genie/releases/tag/cli-0.8.0).
