From 1a46046dc4900ff9e8822359def3b9eb43f837eb Mon Sep 17 00:00:00 2001
From: "Brian M. Carr" <brian.carr@engine.com>
Date: Thu, 8 Oct 2026 12:11:48 -0500
Subject: [PATCH] Resolve reference links in every emitted string and scrub
 plain-text fields

Comments were emitted raw: reference links were only resolved when
referenceLinkTarget was set, never failed the build, and annotation text
bypassed both resolution and scrubbing. Comment text also kept the leading
space of every `// ` line.

- Read comments through protoc-utils' cleaned Comment, which dedents them.
- Resolve references with protoc-utils-markdown in every description,
  summary, and title, from comments and annotations alike, against every
  file in the request. Elements with no anchor in the document render as
  code instead of failing.
- Add resolveReferenceLinksMode (NONE / WARN / FAIL_ON_INVALID, default
  FAIL_ON_INVALID) and referenceLink=<label>=<URL> overrides, matching
  protoc-gen-markdown.
- Scrub Markdown from plain-text fields: annotation summaries, titles, and
  OAuth scope descriptions.
- Emit SecurityScheme.description, which was dropped.

BREAKING CHANGE: unresolved or ambiguous reference links now fail the run by
default; set resolveReferenceLinksMode=WARN to keep the previous behavior.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |   2 +-
 README.md                                     |  58 +--
 build.gradle.kts                              |   1 +
 examples/README.md                            |   5 +
 examples/build.gradle.kts                     |   3 +
 examples/src/complete/kotlin/CompleteTest.kt  |   1 +
 ...le.complete.StorefrontService.openapi.yaml |  35 +-
 ....enums.OrderService.openapi.json.run1.json |   2 +-
 ....enums.OrderService.openapi.json.run2.json |   2 +-
 ....enums.OrderService.openapi.json.run3.json |   2 +-
 ....enums.OrderService.openapi.json.run4.json |   2 +-
 ...Service.openapi.json.BodyHandlingTest.json |  10 +-
 ...oService.openapi.json.AutoMappingTest.json |   2 +-
 ...le.errorResponses.ItemService.openapi.json |  10 +-
 ...ineFieldSchema.ArchiveService.openapi.json |   8 +-
 ...inlineSchemas.EnvelopeService.openapi.json |  18 +-
 ...chemasGlobal.InventoryService.openapi.json |  12 +-
 .../src/referenceLinkResolution/README.md     |  17 +
 .../kotlin/ReferenceLinkResolutionTest.kt     | 143 ++++++
 .../proto/catalog.proto                       | 101 +++++
 .../proto/shared.proto                        |  21 +
 .../resources/none.openapi.json               | 128 ++++++
 .../resources/redoc.openapi.json              | 149 +++++++
 .../resources/swagger.openapi.json            | 130 ++++++
 examples/src/referenceLinks/README.md         |   5 +-
 ...enapi.example.serviceOrdering.openapi.json |   6 +-
 ....version.PinnedVersionService.openapi.json |   2 +-
 ...le.version.UnversionedService.openapi.json |   2 +-
 ...ellKnownTypes.EnvelopeService.openapi.json |   8 +-
 gradle/libs.versions.toml                     |   3 +-
 .../engine/protoc/openapi/ProtocGenOpenAPI.kt |  92 +++-
 .../engine/protoc/openapi/compile/Compiler.kt | 132 +++---
 .../protoc/openapi/compile/Descriptions.kt    | 237 ++++++++++
 .../protoc/openapi/compile/PathsBuilder.kt    | 194 ++------
 .../openapi/compile/ReferenceLinkResolver.kt  | 415 ------------------
 .../openapi/compile/json/JsonContext.kt       |   6 +
 .../openapi/compile/json/OpenApiSerializer.kt |  41 +-
 .../openapi/compile/json/SchemaSerializer.kt  |   6 +-
 38 files changed, 1267 insertions(+), 744 deletions(-)
 create mode 100644 examples/src/referenceLinkResolution/README.md
 create mode 100644 examples/src/referenceLinkResolution/kotlin/ReferenceLinkResolutionTest.kt
 create mode 100644 examples/src/referenceLinkResolution/proto/catalog.proto
 create mode 100644 examples/src/referenceLinkResolution/proto/shared.proto
 create mode 100644 examples/src/referenceLinkResolution/resources/none.openapi.json
 create mode 100644 examples/src/referenceLinkResolution/resources/redoc.openapi.json
 create mode 100644 examples/src/referenceLinkResolution/resources/swagger.openapi.json
 create mode 100644 src/main/kotlin/com/engine/protoc/openapi/compile/Descriptions.kt
 delete mode 100644 src/main/kotlin/com/engine/protoc/openapi/compile/ReferenceLinkResolver.kt

diff --git a/CLAUDE.md b/CLAUDE.md
index b1cdb3f..e21c08e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,7 +13,7 @@ For engine annotations and the model artifact, read [model/README.md](model/READ
   Houses the `Options` data class (every plugin option lives here as a property with KDoc) and the `from(...)` factory that registers the `Annotations` + `google.api` extension registries before parsing the `CodeGeneratorRequest`.
 - [`compile/Compiler.kt`](src/main/kotlin/com/engine/protoc/openapi/compile/Compiler.kt) — internal compiler.
   `compile()` dispatches to `compileMerged()` or `compileUnmerged()` based on `options.merge`.
-- [`compile/`](src/main/kotlin/com/engine/protoc/openapi/compile) — supporting builders and indices: `SchemaBuilder`, `PathsBuilder`, `MessageIndex`, `EnumIndex`, `RpcIndex`, `SchemaKeyResolver`, plus the `json/` serializers.
+- [`compile/`](src/main/kotlin/com/engine/protoc/openapi/compile) — supporting builders and indices: `SchemaBuilder`, `PathsBuilder`, `Descriptions` (every emitted description/summary/title: reference-link resolution and plain-text scrubbing), `MessageIndex`, `EnumIndex`, `RpcIndex`, `SchemaKeyResolver`, plus the `json/` serializers.
 
 ## Working Reminders
 
diff --git a/README.md b/README.md
index e515ef9..168ee1e 100644
--- a/README.md
+++ b/README.md
@@ -96,33 +96,35 @@ Click the option name to jump to its KDoc for full semantics, precedence rules,
 
 | name | type | default | summary |
 |---|---|---|---|
-| [`alwaysPrintPrimitiveFields`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L266) | boolean | `false` | Add every non-repeated, non-message field to `required`. Pair with Envoy's `always_print_primitive_fields`. |
-| [`autoMapping`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L251) | boolean | `false` | Auto-map gRPC methods without a `google.api.http` annotation to `POST /<package>.<ServiceName>/<MethodName>`. Mirrors Envoy's `auto_mapping`. |
-| [`autoTagServices`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L116) | boolean | `false` | Tag every operation with its enclosing service name and emit a top-level `tags` entry per service using the service's proto comment as the description. |
-| [`convertGrpcStatus`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L309) | boolean | `false` | Add a `"default"` response entry to every operation whose JSON body is an inline `google.rpc.Status` schema. Mirrors Envoy's `convert_grpc_status`. |
-| [`enumValueFormat`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L232) | enum | `CANONICAL` | How enum values are written into OAS `enum` arrays: `CANONICAL`, `NUMERIC_VALUE`, or `LOWER_CASE`. Pair with Envoy's `always_print_enums_as_ints` / `case_insensitive_enum_parsing`. |
-| [`inlineEnums`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L180) | boolean | `false` | Emit enum values inline at every reference instead of as a shared `$ref` in `components/schemas`. |
-| [`inlineRequestSchemas`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L198) | boolean | `true` | Global default for inlining each RPC's request body schema at the use site. Per-method `inline_request` annotation overrides. |
-| [`inlineResponseSchemas`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L210) | boolean | `true` | Global default for inlining each RPC's response body schema at the use site. Per-method `inline_response` annotation overrides. |
-| [`logFile`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L365) | string | — | File path the SLF4J binding writes records to. When unset, records go to standard error. |
-| [`logLevel`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L353) | enum | `ERROR` | SLF4J threshold (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`) applied to every logger the plugin and its dependencies create. |
-| [`merge`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L36) | boolean | `false` | Combine every service across every target file into a single OpenAPI document instead of one document per service. |
-| [`outputFormat`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L99) | enum | `JSON` | Serialization format of generated documents: `JSON` (default) or `YAML`. |
-| [`preserveProtoFieldNames`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L285) | boolean | `false` | Use raw proto field names (e.g. `my_field`) as schema property keys instead of `json_name` or lowerCamelCase. Pair with Envoy's `preserve_proto_field_names`. |
-| [`referenceLinkTarget`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L439) | enum | `NONE` | Renderer dialect that CommonMark reference links (`[Type]`, `[Service.Method]`) in `description` fields resolve to: `NONE` (default — resolution off, brackets untouched), `SWAGGER_UI` (operations + tags), or `REDOC` (operations + tags + generated schema sections). When resolution is enabled, unresolved references are stripped of their brackets and rendered as an inline code span (`` `Property` ``), with a warning. |
-| [`schemaNamespaceCasing`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L145) | enum | `NONE` | Case transformation applied to package segments of a namespaced schema key. `NONE`, `CAPITALIZED`, or `UPPER_CASE`. |
-| [`schemaNamespaceSeparator`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L136) | enum | `NONE` | Separator placed between package segments of a namespaced schema key. `NONE`, `UNDERSCORE`, `DASH`, or `DOT`. |
-| [`schemaNamespaceStrategy`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L129) | enum | `NONE` | Controls which package segments are prepended to schema keys in `components/schemas`. `NONE`, `FULL_PACKAGE`, or `SIMPLIFIED_PACKAGE`. |
-| [`schemaNamespaceVersionExtraction`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L156) | boolean | `false` | Move package segments that look like proto API version identifiers (e.g. `v1`, `v2beta1`) to the end of the schema key. |
-| [`serviceExclude`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L403) | regex | — | Exclude services whose fully-qualified name contains a match, even if they also matched `serviceInclude`. |
-| [`serviceInclude`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L390) | regex | `^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)*$` | Only include services whose fully-qualified name contains a match. Schemas referenced only by excluded services are also omitted. |
-| [`setSchemaTitleToProtoSimpleName`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L169) | boolean | `false` | Add a `"title"` field to each schema in `components/schemas` set to the unqualified proto type name. |
-| [`streamNewlineDelimited`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L324) | boolean | `false` | Document server-streaming responses with content-type `application/x-ndjson`. Mirrors Envoy's `stream_newline_delimited`. |
-| [`streamSseStyleDelimited`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L339) | boolean | `false` | Document server-streaming responses with content-type `text/event-stream`. Mirrors Envoy's `stream_sse_style_delimited`. Takes precedence over `streamNewlineDelimited`. |
-| [`suppressDefaultEnumValues`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L221) | boolean | `false` | Omit enum values whose proto number is `0` (the proto3 default value convention) from all OAS enum value lists. |
-| [`validateOutput`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L68) | boolean | `false` | Validate each generated document against the official OAS 3.1.1 schema. Issues are logged at `WARN`. See [`validationErrorsAreFatal`](#L88) to also fail the compile. |
-| [`validationErrorsAreFatal`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L88) | boolean | `false` | When `true`, validation issues are also written to the protoc error and fail the compile. No effect unless `validateOutput` is also `true`. |
-| [`version`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L54) | string | — | Fallback `info.version` for documents whose annotations do not specify one. |
+| [`alwaysPrintPrimitiveFields`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L269) | boolean | `false` | Add every non-repeated, non-message field to `required`. Pair with Envoy's `always_print_primitive_fields`. |
+| [`autoMapping`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L254) | boolean | `false` | Auto-map gRPC methods without a `google.api.http` annotation to `POST /<package>.<ServiceName>/<MethodName>`. Mirrors Envoy's `auto_mapping`. |
+| [`autoTagServices`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L119) | boolean | `false` | Tag every operation with its enclosing service name and emit a top-level `tags` entry per service using the service's proto comment as the description. |
+| [`convertGrpcStatus`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L312) | boolean | `false` | Add a `"default"` response entry to every operation whose JSON body is an inline `google.rpc.Status` schema. Mirrors Envoy's `convert_grpc_status`. |
+| [`enumValueFormat`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L235) | enum | `CANONICAL` | How enum values are written into OAS `enum` arrays: `CANONICAL`, `NUMERIC_VALUE`, or `LOWER_CASE`. Pair with Envoy's `always_print_enums_as_ints` / `case_insensitive_enum_parsing`. |
+| [`inlineEnums`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L183) | boolean | `false` | Emit enum values inline at every reference instead of as a shared `$ref` in `components/schemas`. |
+| [`inlineRequestSchemas`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L201) | boolean | `true` | Global default for inlining each RPC's request body schema at the use site. Per-method `inline_request` annotation overrides. |
+| [`inlineResponseSchemas`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L213) | boolean | `true` | Global default for inlining each RPC's response body schema at the use site. Per-method `inline_response` annotation overrides. |
+| [`logFile`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L372) | string | — | File path the SLF4J binding writes records to. When unset, records go to standard error. |
+| [`logLevel`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L360) | enum | `ERROR` | SLF4J threshold (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`) applied to every logger the plugin and its dependencies create. |
+| [`merge`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L39) | boolean | `false` | Combine every service across every target file into a single OpenAPI document instead of one document per service. |
+| [`outputFormat`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L102) | enum | `JSON` | Serialization format of generated documents: `JSON` (default) or `YAML`. |
+| [`preserveProtoFieldNames`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L288) | boolean | `false` | Use raw proto field names (e.g. `my_field`) as schema property keys instead of `json_name` or lowerCamelCase. Pair with Envoy's `preserve_proto_field_names`. |
+| [`referenceLink`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L481) | `<label>=<URL>` (repeatable) | — | Links a reference-link label to an external URL, e.g. `referenceLink=google.rpc.Status=cloud.google.com/...` makes `[Status.details][google.rpc.Status]` a link. A URL with no scheme gets `https://`, since protoc reserves `:` in `--openapi_out`. |
+| [`referenceLinkTarget`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L444) | enum | `NONE` | Renderer dialect that resolved reference links point at: `NONE` (default — no links; resolved references render as code), `SWAGGER_UI` (operations + tags), or `REDOC` (operations + tags + generated schema sections). References to elements with no anchor in the document render as code. See `resolveReferenceLinksMode`. |
+| [`resolveReferenceLinksMode`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L466) | enum | `FAIL_ON_INVALID` | Resolution of CommonMark reference links (`[Type]`, `[Type.field]`, `[Service.Method]`, `[text][label]`) in every emitted description, summary, and title: `NONE` (text as written), `WARN` (resolve; log unresolved or ambiguous references and render them as code), or `FAIL_ON_INVALID` (as `WARN`, and fail the run listing every bad reference). |
+| [`schemaNamespaceCasing`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L148) | enum | `NONE` | Case transformation applied to package segments of a namespaced schema key. `NONE`, `CAPITALIZED`, or `UPPER_CASE`. |
+| [`schemaNamespaceSeparator`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L139) | enum | `NONE` | Separator placed between package segments of a namespaced schema key. `NONE`, `UNDERSCORE`, `DASH`, or `DOT`. |
+| [`schemaNamespaceStrategy`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L132) | enum | `NONE` | Controls which package segments are prepended to schema keys in `components/schemas`. `NONE`, `FULL_PACKAGE`, or `SIMPLIFIED_PACKAGE`. |
+| [`schemaNamespaceVersionExtraction`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L159) | boolean | `false` | Move package segments that look like proto API version identifiers (e.g. `v1`, `v2beta1`) to the end of the schema key. |
+| [`serviceExclude`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L410) | regex | — | Exclude services whose fully-qualified name contains a match, even if they also matched `serviceInclude`. |
+| [`serviceInclude`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L397) | regex | `^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)*$` | Only include services whose fully-qualified name contains a match. Schemas referenced only by excluded services are also omitted. |
+| [`setSchemaTitleToProtoSimpleName`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L172) | boolean | `false` | Add a `"title"` field to each schema in `components/schemas` set to the unqualified proto type name. |
+| [`streamNewlineDelimited`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L331) | boolean | `false` | Document server-streaming responses with content-type `application/x-ndjson`. Mirrors Envoy's `stream_newline_delimited`. |
+| [`streamSseStyleDelimited`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L346) | boolean | `false` | Document server-streaming responses with content-type `text/event-stream`. Mirrors Envoy's `stream_sse_style_delimited`. Takes precedence over `streamNewlineDelimited`. |
+| [`suppressDefaultEnumValues`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L224) | boolean | `false` | Omit enum values whose proto number is `0` (the proto3 default value convention) from all OAS enum value lists. |
+| [`validateOutput`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L71) | boolean | `false` | Validate each generated document against the official OAS 3.1.1 schema. Issues are logged at `WARN`. See [`validationErrorsAreFatal`](#L91) to also fail the compile. |
+| [`validationErrorsAreFatal`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L91) | boolean | `false` | When `true`, validation issues are also written to the protoc error and fail the compile. No effect unless `validateOutput` is also `true`. |
+| [`version`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L57) | string | — | Fallback `info.version` for documents whose annotations do not specify one. |
 
 Enum-valued options accept their values case-insensitively.
 
@@ -140,7 +142,7 @@ specified in [`google/api/http.proto`](https://github.com/googleapis/googleapis/
 | **`"<field_name>"`** | the value of that single top-level field | every other request field not bound to the URL template |
 
 Auto-derived query parameters use the field's JSON name by default (or the snake_case proto name
-when [`preserveProtoFieldNames`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L285)
+when [`preserveProtoFieldNames`](src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt#L288)
 is set), recurse into nested messages with dotted names (`?address.city=…`), and emit `style=form,
 explode=true` for repeated scalars.  Repeated message and map fields are skipped with a `WARN` log
 since OpenAPI has no faithful query-string representation for them.
diff --git a/build.gradle.kts b/build.gradle.kts
index 9a37665..523e21a 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -71,6 +71,7 @@ dependencies {
 
     implementation(libs.commonmark)
     implementation(libs.engine.protoc.utils)
+    implementation(libs.engine.protoc.utils.markdown)
     implementation(libs.jackson.databind)
     implementation(libs.jackson.dataformat.yaml)
     implementation(libs.kotlin.reflect)
diff --git a/examples/README.md b/examples/README.md
index c26deeb..380affe 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -95,6 +95,11 @@ Covers single error, multiple errors, optional `grpc_code` (emitted as `x-grpc-c
 Demonstrates how the plugin emits inline OpenAPI schemas for structural protobuf well-known types — `Any`, `Struct`, `Value`, `ListValue`, `FieldMask`, and `Empty` — instead of dangling `$ref`s into `components/schemas`.
 Covers both first-party fields that carry these types and the canonical regression case where `google.api.HttpBody` is returned by an RPC and its `extensions` field bottoms out in `google.protobuf.Any`.
 
+### [referenceLinkResolution](src/referenceLinkResolution/README.md)
+
+Demonstrates `resolveReferenceLinksMode` and `referenceLink`: reference links in proto comments and annotation text resolve to anchors, code spans, or external URLs, plain-text `summary` and `title` fields are scrubbed of Markdown, and unresolved or ambiguous references fail the run under `FAIL_ON_INVALID`.
+Compiles one proto set under `FAIL_ON_INVALID`, `WARN` (Redoc and Swagger UI targets), and `NONE`.
+
 ### [referenceLinks](src/referenceLinks/README.md)
 
 Demonstrates the `referenceLinkTarget` option, which rewrites CommonMark reference links (`[Widget]`, `[WidgetService.GetWidget]`) in proto comments into same-document anchors.
diff --git a/examples/build.gradle.kts b/examples/build.gradle.kts
index c551606..991432d 100644
--- a/examples/build.gradle.kts
+++ b/examples/build.gradle.kts
@@ -33,6 +33,8 @@ testing {
             dependencies {
                 implementation(projects.protocGenOpenapi)
                 implementation(projects.protocGenOpenapiModel)
+                // Option types such as ReferenceLinkMode come from protoc-utils-markdown.
+                implementation(libs.engine.protoc.utils.markdown)
 
                 implementation(testFixtures(project()))
 
@@ -76,6 +78,7 @@ testing {
         register<JvmTestSuite>("serviceOrdering")
         register<JvmTestSuite>("errorResponses")
         register<JvmTestSuite>("referenceLinks")
+        register<JvmTestSuite>("referenceLinkResolution")
 
         /*
          * Envoy integration suite: runs Envoy in a container (via testcontainers) and exercises
diff --git a/examples/src/complete/kotlin/CompleteTest.kt b/examples/src/complete/kotlin/CompleteTest.kt
index c685a7c..65d3e32 100644
--- a/examples/src/complete/kotlin/CompleteTest.kt
+++ b/examples/src/complete/kotlin/CompleteTest.kt
@@ -34,6 +34,7 @@ class CompleteTest :
         val generatedFile = response.fileList
             .find { it.name == "engine.protoc.openapi.example.complete.StorefrontService.openapi.yaml" }
             .shouldNotBeNull()
+        GoldenFiles.maybeWriteGolden("complete", generatedFile.name, generatedFile.content)
         val doc: JsonNode = mapper.readTree(generatedFile.content)
         val expected = CompleteTest::class.java.getResourceAsStream("/engine.protoc.openapi.example.complete.StorefrontService.openapi.yaml").shouldNotBeNull().reader().readText()
 
diff --git a/examples/src/complete/resources/engine.protoc.openapi.example.complete.StorefrontService.openapi.yaml b/examples/src/complete/resources/engine.protoc.openapi.example.complete.StorefrontService.openapi.yaml
index 57c1342..9a8d19c 100644
--- a/examples/src/complete/resources/engine.protoc.openapi.example.complete.StorefrontService.openapi.yaml
+++ b/examples/src/complete/resources/engine.protoc.openapi.example.complete.StorefrontService.openapi.yaml
@@ -101,8 +101,8 @@ paths:
     get:
       summary: "Search products"
       description: "Search products.  Exercises query-parameter override precedence\
-        \ (see SearchFilter): both a\n `$ref` parameter and a dotted inline parameter\
-        \ take precedence over auto-derivation, so the\n request's `page_size` and\
+        \ (see SearchFilter): both a\n`$ref` parameter and a dotted inline parameter\
+        \ take precedence over auto-derivation, so the\nrequest's `page_size` and\
         \ `geo.city` fields are not auto-derived as duplicate parameters."
       operationId: "searchProducts"
       tags:
@@ -166,7 +166,7 @@ paths:
       - name: "price"
         in: "query"
         description: "covers SchemaObject.minimum, exclusive_minimum, maximum, exclusive_maximum,\n\
-          \ multiple_of, default, example (SchemaObject.example deprecated field)"
+          multiple_of, default, example (SchemaObject.example deprecated field)"
         required: false
         schema:
           type: "number"
@@ -193,8 +193,7 @@ paths:
       - name: "tags"
         in: "query"
         description: "covers SchemaObject.items, prefix_items, contains, min_contains,\
-          \ max_contains,\n min_items, max_items, unique_items, unevaluated_items\
-          \ (Schema.boolean=false)"
+          \ max_contains,\nmin_items, max_items, unique_items, unevaluated_items (Schema.boolean=false)"
         required: false
         style: "form"
         explode: true
@@ -219,7 +218,7 @@ paths:
       - name: "stockQuantity"
         in: "query"
         description: "covers SchemaObject.deprecated (on field), SchemaObject.examples\
-          \ (repeated Any),\n SchemaObject.title (on field)"
+          \ (repeated Any),\nSchemaObject.title (on field)"
         required: false
         schema:
           type: "integer"
@@ -358,7 +357,7 @@ paths:
       - name: "price"
         in: "query"
         description: "covers SchemaObject.minimum, exclusive_minimum, maximum, exclusive_maximum,\n\
-          \ multiple_of, default, example (SchemaObject.example deprecated field)"
+          multiple_of, default, example (SchemaObject.example deprecated field)"
         required: false
         schema:
           type: "number"
@@ -385,8 +384,7 @@ paths:
       - name: "tags"
         in: "query"
         description: "covers SchemaObject.items, prefix_items, contains, min_contains,\
-          \ max_contains,\n min_items, max_items, unique_items, unevaluated_items\
-          \ (Schema.boolean=false)"
+          \ max_contains,\nmin_items, max_items, unique_items, unevaluated_items (Schema.boolean=false)"
         required: false
         style: "form"
         explode: true
@@ -411,7 +409,7 @@ paths:
       - name: "stockQuantity"
         in: "query"
         description: "covers SchemaObject.deprecated (on field), SchemaObject.examples\
-          \ (repeated Any),\n SchemaObject.title (on field)"
+          \ (repeated Any),\nSchemaObject.title (on field)"
         required: false
         schema:
           type: "integer"
@@ -516,8 +514,8 @@ paths:
     patch:
       summary: "Update order shipping address"
       description: "Update only the shipping address on an existing order.  Exercises\
-        \ the named-field body\n mode: `shipping_address` is the request body string,\
-        \ while the remaining non-path fields\n (`status`, `total`) become URL query\
+        \ the named-field body\nmode: `shipping_address` is the request body string,\
+        \ while the remaining non-path fields\n(`status`, `total`) become URL query\
         \ parameters auto-derived from the Order message."
       operationId: "updateOrderShipping"
       tags:
@@ -792,6 +790,7 @@ components:
       type: "http"
       scheme: "bearer"
       bearerFormat: "JWT"
+      description: "JWT bearer token authentication"
       x-bearer-docs: "https://example.com/auth"
     apiKeyAuth:
       type: "apiKey"
@@ -923,8 +922,8 @@ components:
     Order:
       type: "object"
       description: "Order covers SchemaObject: id ($id), schema ($schema), anchor\
-        \ ($anchor),\n dynamic_anchor ($dynamicAnchor), dynamic_ref ($dynamicRef),\
-        \ defs ($defs),\n uri_ref ($ref at SchemaObject level).\n Order.status field\
+        \ ($anchor),\ndynamic_anchor ($dynamicAnchor), dynamic_ref ($dynamicRef),\
+        \ defs ($defs),\nuri_ref ($ref at SchemaObject level).\nOrder.status field\
         \ covers: content_encoding, content_media_type, content_schema."
       properties:
         orderId:
@@ -992,7 +991,7 @@ components:
           type: "number"
           format: "double"
           description: "covers SchemaObject.minimum, exclusive_minimum, maximum, exclusive_maximum,\n\
-            \ multiple_of, default, example (SchemaObject.example deprecated field)"
+            multiple_of, default, example (SchemaObject.example deprecated field)"
           default: 9.99
           example: 29.99
           multipleOf: 0.01
@@ -1015,7 +1014,7 @@ components:
             type: "string"
             minLength: 1
           description: "covers SchemaObject.items, prefix_items, contains, min_contains,\
-            \ max_contains,\n min_items, max_items, unique_items, unevaluated_items\
+            \ max_contains,\nmin_items, max_items, unique_items, unevaluated_items\
             \ (Schema.boolean=false)"
           prefixItems:
           - type: "string"
@@ -1034,7 +1033,7 @@ components:
           type: "integer"
           format: "int32"
           description: "covers SchemaObject.deprecated (on field), SchemaObject.examples\
-            \ (repeated Any),\n SchemaObject.title (on field)"
+            \ (repeated Any),\nSchemaObject.title (on field)"
           title: "Stock Quantity"
           deprecated: true
           examples:
@@ -1073,7 +1072,7 @@ components:
     ProductList:
       type: "object"
       description: "ProductList covers: all_of (Schema.boolean=true), any_of, one_of,\n\
-        \ not (Schema.boolean=false), if_schema, then_schema, else_schema,\n unevaluated_properties\
+        not (Schema.boolean=false), if_schema, then_schema, else_schema,\nunevaluated_properties\
         \ (Schema.boolean=false), additional_properties_schema (Schema.boolean=true)."
       properties:
         products:
diff --git a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run1.json b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run1.json
index e0bdb8d..a1a2a62 100644
--- a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run1.json
+++ b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run1.json
@@ -59,7 +59,7 @@
       "ReturnRequest": {
         "properties": {
           "affectedStatuses": {
-            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\n suppressDefaultEnumValues = true is set globally.",
+            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\nsuppressDefaultEnumValues = true is set globally.",
             "items": {
               "$ref": "#/components/schemas/OrderStatus"
             },
diff --git a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run2.json b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run2.json
index 06c28a9..5c44702 100644
--- a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run2.json
+++ b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run2.json
@@ -53,7 +53,7 @@
       "ReturnRequest": {
         "properties": {
           "affectedStatuses": {
-            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\n suppressDefaultEnumValues = true is set globally.",
+            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\nsuppressDefaultEnumValues = true is set globally.",
             "items": {
               "description": "The lifecycle status of an order.\n\n- `UNSET` — UNSET is the proto3 conventional default value (number = 0).\n\n- `PENDING` — Order has been received and is awaiting processing.\n\n  Sometimes an enum comment might be multi-line. What happens then?\n\n- `CONFIRMED` — Order has been accepted and payment verified.\n\n- `SHIPPED` — Order has been handed off to the carrier and is in transit.\n\n- `CANCELLED` — Order was voided before or during fulfillment.",
               "enum": [
diff --git a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run3.json b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run3.json
index 833420e..3035226 100644
--- a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run3.json
+++ b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run3.json
@@ -56,7 +56,7 @@
       "ReturnRequest": {
         "properties": {
           "affectedStatuses": {
-            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\n suppressDefaultEnumValues = true is set globally.",
+            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\nsuppressDefaultEnumValues = true is set globally.",
             "items": {
               "$ref": "#/components/schemas/OrderStatus"
             },
diff --git a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run4.json b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run4.json
index e8e698e..9724358 100644
--- a/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run4.json
+++ b/examples/src/enums/resources/engine.protoc.openapi.example.enums.OrderService.openapi.json.run4.json
@@ -50,7 +50,7 @@
       "ReturnRequest": {
         "properties": {
           "affectedStatuses": {
-            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\n suppressDefaultEnumValues = true is set globally.",
+            "description": "Per-value suppress = false keeps REASON_UNSET visible even when\nsuppressDefaultEnumValues = true is set globally.",
             "items": {
               "description": "The lifecycle status of an order.\n\n- `UNSET` — UNSET is the proto3 conventional default value (number = 0).\n\n- `PENDING` — Order has been received and is awaiting processing.\n\n  Sometimes an enum comment might be multi-line. What happens then?\n\n- `CONFIRMED` — Order has been accepted and payment verified.\n\n- `SHIPPED` — Order has been handed off to the carrier and is in transit.\n\n- `CANCELLED` — Order was voided before or during fulfillment.",
               "enum": [
diff --git a/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.BodyService.openapi.json.BodyHandlingTest.json b/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.BodyService.openapi.json.BodyHandlingTest.json
index b1327ec..3611e2b 100644
--- a/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.BodyService.openapi.json.BodyHandlingTest.json
+++ b/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.BodyService.openapi.json.BodyHandlingTest.json
@@ -4,7 +4,7 @@
     "/greet/{your_name}" : {
       "get" : {
         "summary" : "GET with one path-bound field and the rest becoming query parameters.",
-        "description" : "GET with one path-bound field and the rest becoming query parameters.\n Canonical \"REST-style\" mapping.",
+        "description" : "GET with one path-bound field and the rest becoming query parameters.\nCanonical \"REST-style\" mapping.",
         "parameters" : [ {
           "name" : "your_name",
           "in" : "path",
@@ -61,7 +61,7 @@
       },
       "delete" : {
         "summary" : "DELETE with one path-bound field; remaining fields become query parameters.",
-        "description" : "DELETE with one path-bound field; remaining fields become query\n parameters.  Confirms DELETE behaves identically to GET.",
+        "description" : "DELETE with one path-bound field; remaining fields become query\nparameters.  Confirms DELETE behaves identically to GET.",
         "parameters" : [ {
           "name" : "your_name",
           "in" : "path",
@@ -120,7 +120,7 @@
     "/echo" : {
       "post" : {
         "summary" : "POST with body unset — Envoy permits this and binds all non-path fields as query parameters regardless of verb.",
-        "description" : "POST with body unset — Envoy permits this and binds all non-path fields\n as query parameters regardless of verb.  Atypical, but spec-allowed.",
+        "description" : "POST with body unset — Envoy permits this and binds all non-path fields\nas query parameters regardless of verb.  Atypical, but spec-allowed.",
         "parameters" : [ {
           "name" : "yourName",
           "in" : "query",
@@ -179,7 +179,7 @@
     "/greet/named" : {
       "post" : {
         "summary" : "POST with body naming a single sub-field; remaining non-path fields become query parameters.",
-        "description" : "POST with body naming a single sub-field; remaining non-path fields\n become query parameters.",
+        "description" : "POST with body naming a single sub-field; remaining non-path fields\nbecome query parameters.",
         "parameters" : [ {
           "name" : "yourName",
           "in" : "query",
@@ -234,7 +234,7 @@
   },
   "info" : {
     "title" : "BodyService",
-    "description" : "BodyService exercises the three HttpRule.body modes (unset, \"*\", and a named\n field) across multiple HTTP verbs.  Each RPC asserts the canonical\n transcoder behaviour described in google/api/http.proto: with body unset\n every non-path field becomes a URL query parameter; with body=\"<field>\"\n that field is the request body and the rest become query parameters.",
+    "description" : "BodyService exercises the three HttpRule.body modes (unset, \"*\", and a named\nfield) across multiple HTTP verbs.  Each RPC asserts the canonical\ntranscoder behaviour described in google/api/http.proto: with body unset\nevery non-path field becomes a URL query parameter; with body=\"<field>\"\nthat field is the request body and the rest become query parameters.",
     "version" : "1.0.0"
   },
   "components" : {
diff --git a/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.HelloService.openapi.json.AutoMappingTest.json b/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.HelloService.openapi.json.AutoMappingTest.json
index 064de67..3e02872 100644
--- a/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.HelloService.openapi.json.AutoMappingTest.json
+++ b/examples/src/envoy/resources/engine.protoc.openapi.example.envoy.HelloService.openapi.json.AutoMappingTest.json
@@ -42,7 +42,7 @@
   "paths": {
     "/engine.protoc.openapi.example.envoy.HelloService/PingHello": {
       "post": {
-        "description": "PingHello intentionally has no google.api.http annotation so it can be\n exercised via Envoy's auto_mapping feature.",
+        "description": "PingHello intentionally has no google.api.http annotation so it can be\nexercised via Envoy's auto_mapping feature.",
         "requestBody": {
           "content": {
             "application/json": {
diff --git a/examples/src/errorResponses/resources/engine.protoc.openapi.example.errorResponses.ItemService.openapi.json b/examples/src/errorResponses/resources/engine.protoc.openapi.example.errorResponses.ItemService.openapi.json
index 89d4563..01dbdca 100644
--- a/examples/src/errorResponses/resources/engine.protoc.openapi.example.errorResponses.ItemService.openapi.json
+++ b/examples/src/errorResponses/resources/engine.protoc.openapi.example.errorResponses.ItemService.openapi.json
@@ -3,7 +3,7 @@
   "paths" : {
     "/items/{id}" : {
       "get" : {
-        "summary" : "Single error scenario, with \"grpc_code\" to drive the example payload.",
+        "summary" : "Single error scenario, with grpc_code to drive the example payload.",
         "description" : "Single error scenario, with `grpc_code` to drive the example payload.",
         "parameters" : [ {
           "name" : "id",
@@ -63,8 +63,8 @@
         }
       },
       "put" : {
-        "summary" : "Collision between an explicit \"responses\" entry and an \"error_responses\" entry at the same status.",
-        "description" : "Collision between an explicit `responses` entry and an `error_responses` entry at the\n same status.  The shortcut wins (last-write-wins); the compiler emits a WARN.",
+        "summary" : "Collision between an explicit responses entry and an error_responses entry at the same status.",
+        "description" : "Collision between an explicit `responses` entry and an `error_responses` entry at the\nsame status.  The shortcut wins (last-write-wins); the compiler emits a WARN.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -133,8 +133,8 @@
         }
       },
       "delete" : {
-        "summary" : "Duplicate status within \"error_responses\" itself.",
-        "description" : "Duplicate status within `error_responses` itself.  The compiler emits a WARN and the\n last entry wins.",
+        "summary" : "Duplicate status within error_responses itself.",
+        "description" : "Duplicate status within `error_responses` itself.  The compiler emits a WARN and the\nlast entry wins.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
diff --git a/examples/src/inlineFieldSchema/resources/engine.protoc.openapi.example.inlineFieldSchema.ArchiveService.openapi.json b/examples/src/inlineFieldSchema/resources/engine.protoc.openapi.example.inlineFieldSchema.ArchiveService.openapi.json
index f5c8fe9..4084869 100644
--- a/examples/src/inlineFieldSchema/resources/engine.protoc.openapi.example.inlineFieldSchema.ArchiveService.openapi.json
+++ b/examples/src/inlineFieldSchema/resources/engine.protoc.openapi.example.inlineFieldSchema.ArchiveService.openapi.json
@@ -4,7 +4,7 @@
     "/archives/{id}" : {
       "get" : {
         "summary" : "Archive is in components.",
-        "description" : "Archive is in components.  Its `manifest` field is `inline`d, so the inline\n expansion appears inside the Archive component schema (and inside every $ref chain\n that reaches Archive).  Manifest itself is also in components via GetManifest below;\n the inline expansion's nested `entry` field $refs Entry.",
+        "description" : "Archive is in components.  Its `manifest` field is `inline`d, so the inline\nexpansion appears inside the Archive component schema (and inside every $ref chain\nthat reaches Archive).  Manifest itself is also in components via GetManifest below;\nthe inline expansion's nested `entry` field $refs Entry.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -56,7 +56,7 @@
     "/previews/{id}" : {
       "get" : {
         "summary" : "Preview is in components.",
-        "description" : "Preview is in components.  Its `snapshot` field is `inline`d, and Snapshot is\n reached only through this field — so Snapshot and Tag are absent from components and\n expand inline inside the Preview component schema.",
+        "description" : "Preview is in components.  Its `snapshot` field is `inline`d, and Snapshot is\nreached only through this field — so Snapshot and Tag are absent from components and\nexpand inline inside the Preview component schema.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -88,7 +88,7 @@
     "schemas" : {
       "Archive" : {
         "type" : "object",
-        "description" : "An archive carries its manifest as an inline field.  Because Manifest is also returned\n directly by GetManifest below (non-inline), it stays in components and the inline expansion\n here `$refs` into the component schema for its nested `entry` field.",
+        "description" : "An archive carries its manifest as an inline field.  Because Manifest is also returned\ndirectly by GetManifest below (non-inline), it stays in components and the inline expansion\nhere `$refs` into the component schema for its nested `entry` field.",
         "properties" : {
           "id" : {
             "type" : "string"
@@ -142,7 +142,7 @@
       },
       "Preview" : {
         "type" : "object",
-        "description" : "A preview carries a snapshot reachable only through the inline field below — so neither\n Snapshot nor its Tag sub-field appear in components/schemas; both expand inline.",
+        "description" : "A preview carries a snapshot reachable only through the inline field below — so neither\nSnapshot nor its Tag sub-field appear in components/schemas; both expand inline.",
         "properties" : {
           "id" : {
             "type" : "string"
diff --git a/examples/src/inlineSchemas/resources/engine.protoc.openapi.example.inlineSchemas.EnvelopeService.openapi.json b/examples/src/inlineSchemas/resources/engine.protoc.openapi.example.inlineSchemas.EnvelopeService.openapi.json
index 9e648ae..bb08d68 100644
--- a/examples/src/inlineSchemas/resources/engine.protoc.openapi.example.inlineSchemas.EnvelopeService.openapi.json
+++ b/examples/src/inlineSchemas/resources/engine.protoc.openapi.example.inlineSchemas.EnvelopeService.openapi.json
@@ -30,7 +30,7 @@
     "/envelopes/{id}/peek" : {
       "get" : {
         "summary" : "Inline response: the response schema is inlined, but Envelope is still in components (because GetEnvelope above $refs it), so the inline body $refs Envelope rather than expanding it.",
-        "description" : "Inline response: the response schema is inlined, but Envelope is still in components\n (because GetEnvelope above $refs it), so the inline body $refs Envelope rather than\n expanding it.",
+        "description" : "Inline response: the response schema is inlined, but Envelope is still in components\n(because GetEnvelope above $refs it), so the inline body $refs Envelope rather than\nexpanding it.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -46,7 +46,7 @@
               "application/json" : {
                 "schema" : {
                   "type" : "object",
-                  "description" : "A shared \"envelope\" type referenced from two RPCs: one that inlines its response, one that\n emits a $ref.  The non-inline reference keeps Envelope in components/schemas, and the inline\n reference $refs into that same component.",
+                  "description" : "A shared \"envelope\" type referenced from two RPCs: one that inlines its response, one that\nemits a $ref.  The non-inline reference keeps Envelope in components/schemas, and the inline\nreference $refs into that same component.",
                   "properties" : {
                     "id" : {
                       "type" : "string"
@@ -65,7 +65,7 @@
     "/notes/{id}" : {
       "get" : {
         "summary" : "Inline response of a type that is reached only through this inline path.",
-        "description" : "Inline response of a type that is reached *only* through this inline path.  PrivateNote\n and its NoteAttachment field are therefore absent from components — both expand inline\n at this single site.",
+        "description" : "Inline response of a type that is reached *only* through this inline path.  PrivateNote\nand its NoteAttachment field are therefore absent from components — both expand inline\nat this single site.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -81,14 +81,14 @@
               "application/json" : {
                 "schema" : {
                   "type" : "object",
-                  "description" : "A type reached only through an inlined RPC response.  The transitivity rule omits it from\n components/schemas; its schema appears once, inline, at the response site.",
+                  "description" : "A type reached only through an inlined RPC response.  The transitivity rule omits it from\ncomponents/schemas; its schema appears once, inline, at the response site.",
                   "properties" : {
                     "author" : {
                       "type" : "string"
                     },
                     "attachment" : {
                       "type" : "object",
-                      "description" : "Reached only via PrivateNote, which is itself inline-only — so this transitively gets\n expanded inline too.",
+                      "description" : "Reached only via PrivateNote, which is itself inline-only — so this transitively gets\nexpanded inline too.",
                       "properties" : {
                         "mimeType" : {
                           "type" : "string"
@@ -110,7 +110,7 @@
     "/envelopes/{envelope_id}" : {
       "post" : {
         "summary" : "Inline request: the body's referenced message (Envelope, via body: \"envelope\") is inlined at the requestBody site.",
-        "description" : "Inline request: the body's referenced message (Envelope, via body: \"envelope\") is\n inlined at the requestBody site.  Envelope is also in components from the GetEnvelope\n RPC above, so its nested Payload $ref is preserved (Payload is in components too).",
+        "description" : "Inline request: the body's referenced message (Envelope, via body: \"envelope\") is\ninlined at the requestBody site.  Envelope is also in components from the GetEnvelope\nRPC above, so its nested Payload $ref is preserved (Payload is in components too).",
         "parameters" : [ {
           "name" : "envelope_id",
           "in" : "path",
@@ -125,7 +125,7 @@
             "application/json" : {
               "schema" : {
                 "type" : "object",
-                "description" : "A shared \"envelope\" type referenced from two RPCs: one that inlines its response, one that\n emits a $ref.  The non-inline reference keeps Envelope in components/schemas, and the inline\n reference $refs into that same component.",
+                "description" : "A shared \"envelope\" type referenced from two RPCs: one that inlines its response, one that\nemits a $ref.  The non-inline reference keeps Envelope in components/schemas, and the inline\nreference $refs into that same component.",
                 "properties" : {
                   "id" : {
                     "type" : "string"
@@ -161,7 +161,7 @@
     "schemas" : {
       "Envelope" : {
         "type" : "object",
-        "description" : "A shared \"envelope\" type referenced from two RPCs: one that inlines its response, one that\n emits a $ref.  The non-inline reference keeps Envelope in components/schemas, and the inline\n reference $refs into that same component.",
+        "description" : "A shared \"envelope\" type referenced from two RPCs: one that inlines its response, one that\nemits a $ref.  The non-inline reference keeps Envelope in components/schemas, and the inline\nreference $refs into that same component.",
         "properties" : {
           "id" : {
             "type" : "string"
@@ -173,7 +173,7 @@
       },
       "Payload" : {
         "type" : "object",
-        "description" : "A shared inner message embedded within Envelope.  Because it's reached from a non-inlined\n path (Envelope is in components), Payload is also in components.",
+        "description" : "A shared inner message embedded within Envelope.  Because it's reached from a non-inlined\npath (Envelope is in components), Payload is also in components.",
         "properties" : {
           "kind" : {
             "type" : "string"
diff --git a/examples/src/inlineSchemasGlobal/resources/engine.protoc.openapi.example.inlineSchemasGlobal.InventoryService.openapi.json b/examples/src/inlineSchemasGlobal/resources/engine.protoc.openapi.example.inlineSchemasGlobal.InventoryService.openapi.json
index 8df568f..79e674e 100644
--- a/examples/src/inlineSchemasGlobal/resources/engine.protoc.openapi.example.inlineSchemasGlobal.InventoryService.openapi.json
+++ b/examples/src/inlineSchemasGlobal/resources/engine.protoc.openapi.example.inlineSchemasGlobal.InventoryService.openapi.json
@@ -4,7 +4,7 @@
     "/widgets/{id}" : {
       "get" : {
         "summary" : "No method-level annotation: inherits the global inlineResponseSchemas=true default, so the Widget response schema is inlined directly at the use site.",
-        "description" : "No method-level annotation: inherits the global inlineResponseSchemas=true default, so the\n Widget response schema is inlined directly at the use site.  Widget is reached only via\n inlined paths in this service, so it never lands in components/schemas.",
+        "description" : "No method-level annotation: inherits the global inlineResponseSchemas=true default, so the\nWidget response schema is inlined directly at the use site.  Widget is reached only via\ninlined paths in this service, so it never lands in components/schemas.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -39,7 +39,7 @@
     "/gadgets/{id}" : {
       "get" : {
         "summary" : "Per-method override: inline_response=false forces a $ref to components/schemas even though the global default is true.",
-        "description" : "Per-method override: inline_response=false forces a $ref to components/schemas even though\n the global default is true.  Because of this non-inlined path, Gadget appears in components\n and the other (inlined) Gadget call sites $ref into it.",
+        "description" : "Per-method override: inline_response=false forces a $ref to components/schemas even though\nthe global default is true.  Because of this non-inlined path, Gadget appears in components\nand the other (inlined) Gadget call sites $ref into it.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -65,7 +65,7 @@
     "/widgets/{envelope_id}" : {
       "post" : {
         "summary" : "No method-level annotation: inherits the global inlineRequestSchemas=true default, so the request body schema is inlined.",
-        "description" : "No method-level annotation: inherits the global inlineRequestSchemas=true default, so the\n request body schema is inlined.",
+        "description" : "No method-level annotation: inherits the global inlineRequestSchemas=true default, so the\nrequest body schema is inlined.",
         "parameters" : [ {
           "name" : "envelope_id",
           "in" : "path",
@@ -119,7 +119,7 @@
     "/gadgets/{envelope_id}" : {
       "post" : {
         "summary" : "Per-method override: inline_request=false forces a $ref to components/schemas for the request body even though the global default is true.",
-        "description" : "Per-method override: inline_request=false forces a $ref to components/schemas for the\n request body even though the global default is true.",
+        "description" : "Per-method override: inline_request=false forces a $ref to components/schemas for the\nrequest body even though the global default is true.",
         "parameters" : [ {
           "name" : "envelope_id",
           "in" : "path",
@@ -145,7 +145,7 @@
               "application/json" : {
                 "schema" : {
                   "type" : "object",
-                  "description" : "Reached through at least one non-inlined RPC (GetGadget with inline_response=false),\n so it lands in components/schemas and inlined sites $ref into it.",
+                  "description" : "Reached through at least one non-inlined RPC (GetGadget with inline_response=false),\nso it lands in components/schemas and inlined sites $ref into it.",
                   "properties" : {
                     "id" : {
                       "type" : "string"
@@ -170,7 +170,7 @@
     "schemas" : {
       "Gadget" : {
         "type" : "object",
-        "description" : "Reached through at least one non-inlined RPC (GetGadget with inline_response=false),\n so it lands in components/schemas and inlined sites $ref into it.",
+        "description" : "Reached through at least one non-inlined RPC (GetGadget with inline_response=false),\nso it lands in components/schemas and inlined sites $ref into it.",
         "properties" : {
           "id" : {
             "type" : "string"
diff --git a/examples/src/referenceLinkResolution/README.md b/examples/src/referenceLinkResolution/README.md
new file mode 100644
index 0000000..c82df4f
--- /dev/null
+++ b/examples/src/referenceLinkResolution/README.md
@@ -0,0 +1,17 @@
+# referenceLinkResolution
+
+Demonstrates the `resolveReferenceLinksMode` and `referenceLink` options.
+
+Every string the plugin emits is either CommonMark (`description`) or plain text (`summary`, `title`), whether it comes from a proto comment or an `engine.protoc.openapi` annotation.
+Reference links (`[Gizmo]`, `[Gizmo.name]`, `[CatalogService.GetGizmo]`, `[display text][label]`) are resolved in both:
+
+- In CommonMark fields a resolved reference becomes a link to its operation, tag, or schema (per `referenceLinkTarget`), or an inline code span when the element has no anchor in the document — an RPC without an HTTP binding, an imported type that isn't emitted, or any schema under Swagger UI.
+- Labels configured with `referenceLink=<label>=<URL>` link to that URL, so `[Status.details][google.rpc.Status]` can point at external documentation.
+- Plain-text fields keep only the visible text: `Lists **every** [Gizmo] in the `catalog`.` becomes `Lists every Gizmo in the catalog.`
+
+`catalog.proto` contains one unresolved reference (`[NoSuchThing]`) and one ambiguous one (`[Gadget]`, which also names a message in `shared.proto`).
+The suite compiles the same request four ways:
+
+- **`FAIL_ON_INVALID`** — the run fails and `CodeGeneratorResponse.error` lists both bad references.
+- **`WARN` with `REDOC`** and **`WARN` with `SWAGGER_UI`** — the run succeeds, the bad references are logged, and the unresolved one renders as code (`redoc.openapi.json`, `swagger.openapi.json`).
+- **`NONE`** — comments are emitted as written, brackets included (`none.openapi.json`).
diff --git a/examples/src/referenceLinkResolution/kotlin/ReferenceLinkResolutionTest.kt b/examples/src/referenceLinkResolution/kotlin/ReferenceLinkResolutionTest.kt
new file mode 100644
index 0000000..e12737d
--- /dev/null
+++ b/examples/src/referenceLinkResolution/kotlin/ReferenceLinkResolutionTest.kt
@@ -0,0 +1,143 @@
+package com.engine.protoc.openapi.example
+
+import com.engine.protoc.openapi.ProtocGenOpenAPI
+import com.engine.protoc.util.markdown.ReferenceLinkMode
+import io.kotest.assertions.assertSoftly
+import io.kotest.assertions.withClue
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.nulls.shouldNotBeNull
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import tools.jackson.databind.JsonNode
+import tools.jackson.databind.ObjectMapper
+
+/**
+ * Exercises `resolveReferenceLinksMode` and `referenceLink` across every kind of emitted string:
+ * proto comments and annotation descriptions resolve to anchors or code spans, plain-text
+ * summaries and titles are scrubbed of Markdown, and unresolved or ambiguous references fail the
+ * run under `FAIL_ON_INVALID`.
+ */
+class ReferenceLinkResolutionTest :
+    FunSpec({
+
+        assertSoftly = true
+
+        fun compile(
+            mode: ReferenceLinkMode,
+            target: ProtocGenOpenAPI.Options.ReferenceLinkTarget,
+        ) = ProtocGenOpenAPI.from(
+            ReferenceLinkResolutionTest::class.java.getResourceAsStream("/code-generator-request.binpb").shouldNotBeNull(),
+        ) {
+            merge = true
+            autoTagServices = true
+            inlineRequestSchemas = false
+            inlineResponseSchemas = false
+            validateOutput = true
+            resolveReferenceLinksMode = mode
+            referenceLinkTarget = target
+            referenceLink = mapOf("google.rpc.Status" to "https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status")
+        }.compile()
+
+        val mapper = ObjectMapper()
+
+        context("FAIL_ON_INVALID") {
+            val response = compile(ReferenceLinkMode.FAIL_ON_INVALID, ProtocGenOpenAPI.Options.ReferenceLinkTarget.REDOC)
+
+            test("fails the run listing each bad reference once") {
+                response.error shouldContain "protoc-gen-openapi failed:\n2 reference-link failures under resolveReferenceLinksMode=FAIL_ON_INVALID:"
+                response.error shouldContain
+                    "catalog.proto :: engine.protoc.openapi.example.referenceLinkResolution.catalog.ListGizmosRequest.filter :: [NoSuchThing] — no matching"
+                response.error shouldContain
+                    "catalog.proto :: engine.protoc.openapi.example.referenceLinkResolution.catalog.Gadget :: [Gadget] — ambiguous; candidates:"
+            }
+        }
+
+        context("WARN with REDOC") {
+            val response = compile(ReferenceLinkMode.WARN, ProtocGenOpenAPI.Options.ReferenceLinkTarget.REDOC)
+            val content = response.fileList.single().content
+            GoldenFiles.maybeWriteGolden("referenceLinkResolution", "redoc.openapi.json", content)
+            val doc: JsonNode = mapper.readTree(content)
+            val getGizmo = doc["paths"]["/gizmos/{id}"]["get"]
+            val listGizmos = doc["paths"]["/gizmos"]["get"]
+            val tag = doc["tags"].first { it["name"].asString() == "CatalogService" }
+
+            test("succeeds") { response.error shouldBe "" }
+
+            test("comments resolve to anchors, external links, and code spans") {
+                tag["description"].asString() shouldBe
+                    """
+                    |Manages [Gizmo](#tag/Gizmo) resources.  Fetch one with [GetGizmo](#operation/CatalogService_GetGizmo); on failure, details are in
+                    |[Status.details](https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status).
+                    |
+                    |Unmapped RPCs like `CatalogService.Reindex` have no operation, and imported types like
+                    |`engine.protoc.openapi.example.referenceLinkResolution.shared.Money` have no schema here, so both render as code.
+                    """.trimMargin()
+            }
+
+            test("multi-line comments are dedented and keep their Markdown structure") {
+                getGizmo["description"].asString() shouldContain "\n\nFurther notes:\n\n- `id` must be non-empty\n  and stable\n- see [ListGizmos](#operation/CatalogService_ListGizmos) for collections"
+            }
+
+            test("summaries are plain text") {
+                getGizmo["summary"].asString() shouldBe "Gets a single Gizmo by GetGizmoRequest.id."
+                listGizmos["summary"].asString() shouldBe "Lists every Gizmo in the catalog."
+            }
+
+            test("annotation descriptions and titles are processed too") {
+                listGizmos["description"].asString() shouldBe
+                    "Pages through [Gizmo](#tag/Gizmo) results; see [GetGizmo](#operation/CatalogService_GetGizmo) for one."
+                val pageSize = listGizmos["parameters"].first { it["name"].asString() == "pageSize" }
+                pageSize["description"].asString() shouldBe
+                    "At most 100 [Gizmo](#tag/Gizmo) items."
+                pageSize["schema"]["title"].asString() shouldBe "Page size"
+            }
+
+            test("unresolved references render as code") {
+                val filter = listGizmos["parameters"].first { it["name"].asString() == "filter" }
+                filter["description"].asString() shouldBe "Deliberately broken reference: `NoSuchThing`."
+            }
+        }
+
+        context("WARN with SWAGGER_UI") {
+            val response = compile(ReferenceLinkMode.WARN, ProtocGenOpenAPI.Options.ReferenceLinkTarget.SWAGGER_UI)
+            val content = response.fileList.single().content
+            GoldenFiles.maybeWriteGolden("referenceLinkResolution", "swagger.openapi.json", content)
+            val doc: JsonNode = mapper.readTree(content)
+
+            test("schemas render as code; operations link under their tag") {
+                val tag = doc["tags"].first { it["name"].asString() == "CatalogService" }
+                tag["description"].asString() shouldContain "Manages `Gizmo` resources.  Fetch one with [GetGizmo](#/CatalogService/CatalogService_GetGizmo)"
+            }
+        }
+
+        context("NONE") {
+            val response = compile(ReferenceLinkMode.NONE, ProtocGenOpenAPI.Options.ReferenceLinkTarget.NONE)
+            val content = response.fileList.single().content
+            GoldenFiles.maybeWriteGolden("referenceLinkResolution", "none.openapi.json", content)
+            val doc: JsonNode = mapper.readTree(content)
+
+            test("text is emitted as written, brackets included") {
+                response.error shouldBe ""
+                val listGizmos = doc["paths"]["/gizmos"]["get"]
+                listGizmos["description"].asString() shouldBe "Pages through [Gizmo] results; see [GetGizmo] for one."
+                withClue("plain-text fields still lose their Markdown") {
+                    listGizmos["summary"].asString() shouldNotContain "**"
+                }
+            }
+        }
+
+        test("goldens match") {
+            for ((name, mode, target) in listOf(
+                Triple("redoc.openapi.json", ReferenceLinkMode.WARN, ProtocGenOpenAPI.Options.ReferenceLinkTarget.REDOC),
+                Triple("swagger.openapi.json", ReferenceLinkMode.WARN, ProtocGenOpenAPI.Options.ReferenceLinkTarget.SWAGGER_UI),
+                Triple("none.openapi.json", ReferenceLinkMode.NONE, ProtocGenOpenAPI.Options.ReferenceLinkTarget.NONE),
+            )) {
+                val expected = ReferenceLinkResolutionTest::class.java.getResourceAsStream("/$name").shouldNotBeNull().reader().readText()
+                withClue(name) {
+                    collectJsonDiffs(mapper.readTree(expected), mapper.readTree(compile(mode, target).fileList.single().content))
+                        .forEach { (path, exp, act) -> withClue("at $path") { act shouldBe exp } }
+                }
+            }
+        }
+    })
diff --git a/examples/src/referenceLinkResolution/proto/catalog.proto b/examples/src/referenceLinkResolution/proto/catalog.proto
new file mode 100644
index 0000000..f1921a6
--- /dev/null
+++ b/examples/src/referenceLinkResolution/proto/catalog.proto
@@ -0,0 +1,101 @@
+syntax = "proto3";
+
+// Exercises reference-link resolution, failure modes, external links, and plain-text scrubbing.
+package engine.protoc.openapi.example.referenceLinkResolution.catalog;
+
+option java_package = "com.engine.protoc.openapi.example.referenceLinkResolution.catalog";
+option java_multiple_files = true;
+
+import "google/api/annotations.proto";
+import "engine/protoc/openapi/annotations.proto";
+import "shared.proto";
+
+// Manages [Gizmo] resources.  Fetch one with [GetGizmo]; on failure, details are in
+// [Status.details][google.rpc.Status].
+//
+// Unmapped RPCs like [CatalogService.Reindex] have no operation, and imported types like
+// [engine.protoc.openapi.example.referenceLinkResolution.shared.Money] have no schema here, so both render as code.
+service CatalogService {
+    // Gets a single [Gizmo] by [GetGizmoRequest.id].  Its price is a [engine.protoc.openapi.example.referenceLinkResolution.shared.Money].
+    //
+    // Further notes:
+    //
+    // - `id` must be non-empty
+    //   and stable
+    // - see [ListGizmos] for collections
+    rpc GetGizmo(GetGizmoRequest) returns (Gizmo) {
+        option (google.api.http) = {get: "/gizmos/{id}"};
+    }
+
+    // Lists every [Gizmo].
+    rpc ListGizmos(ListGizmosRequest) returns (ListGizmosResponse) {
+        option (google.api.http) = {get: "/gizmos"};
+        option (engine.protoc.openapi.method) = {
+            operation: {
+                summary: "Lists **every** [Gizmo] in the `catalog`."
+                description: "Pages through [Gizmo] results; see [GetGizmo] for one."
+            }
+        };
+    }
+
+    // Rebuilds the index.  Has no HTTP binding.
+    rpc Reindex(ListGizmosRequest) returns (ListGizmosResponse);
+}
+
+// Request for [CatalogService.GetGizmo].
+message GetGizmoRequest {
+    // Unique id of the [Gizmo] to fetch.
+    string id = 1;
+}
+
+// Request for [CatalogService.ListGizmos].
+message ListGizmosRequest {
+    // Maximum number of items; compare with [Gizmo.name] for sorting.
+    int32 page_size = 1 [(engine.protoc.openapi.field) = {
+        schema: {object: {title: "Page `size`", description: "At most 100 [Gizmo] items."}}
+    }];
+
+    // Deliberately broken reference: [NoSuchThing].
+    string filter = 2;
+}
+
+// A page of [Gizmo] results.
+message ListGizmosResponse {
+    // The items on this page.
+    repeated Gizmo gizmos = 1;
+}
+
+// A gizmo.  Its label is [name]; its state is a [GizmoState].
+//
+// `id` is the stable identifier.
+message Gizmo {
+    // Unique id.
+    string id = 1;
+
+    // Human-readable label.
+    string name = 2;
+
+    // Lifecycle state, one of the [GizmoState] values such as [GIZMO_STATE_ACTIVE].
+    GizmoState state = 3;
+
+    // The gizmo's gadget.
+    Gadget gadget = 4;
+}
+
+// A catalog gadget.  The bare name [Gadget] is ambiguous with [engine.protoc.openapi.example.referenceLinkResolution.shared.Gadget].
+message Gadget {
+    // Gadget id.
+    string id = 1;
+}
+
+// Lifecycle state of a [Gizmo].
+enum GizmoState {
+    // Unset.
+    GIZMO_STATE_UNSPECIFIED = 0;
+
+    // Visible; see [GIZMO_STATE_RETIRED] for the end state.
+    GIZMO_STATE_ACTIVE = 1;
+
+    // No longer offered.
+    GIZMO_STATE_RETIRED = 2;
+}
diff --git a/examples/src/referenceLinkResolution/proto/shared.proto b/examples/src/referenceLinkResolution/proto/shared.proto
new file mode 100644
index 0000000..29e38c1
--- /dev/null
+++ b/examples/src/referenceLinkResolution/proto/shared.proto
@@ -0,0 +1,21 @@
+syntax = "proto3";
+
+// An imported file.  Its types are referenced from comments in catalog.proto but never used by an
+// RPC, so they resolve without being emitted to components/schemas.
+package engine.protoc.openapi.example.referenceLinkResolution.shared;
+
+option java_package = "com.engine.protoc.openapi.example.referenceLinkResolution.shared";
+option java_multiple_files = true;
+
+// An amount of money.
+message Money {
+    // ISO-4217 currency code.
+    string currency_code = 1;
+}
+
+// A gadget from the shared package, colliding with the catalog package's [engine.protoc.openapi.example.referenceLinkResolution.catalog.Gadget] on the
+// short name `Gadget`.
+message Gadget {
+    // Gadget id.
+    string id = 1;
+}
diff --git a/examples/src/referenceLinkResolution/resources/none.openapi.json b/examples/src/referenceLinkResolution/resources/none.openapi.json
new file mode 100644
index 0000000..c32eb48
--- /dev/null
+++ b/examples/src/referenceLinkResolution/resources/none.openapi.json
@@ -0,0 +1,128 @@
+{
+  "openapi" : "3.1.0",
+  "paths" : {
+    "/gizmos/{id}" : {
+      "get" : {
+        "summary" : "Gets a single [Gizmo] by [GetGizmoRequest.id].",
+        "description" : "Gets a single [Gizmo] by [GetGizmoRequest.id].  Its price is a [engine.protoc.openapi.example.referenceLinkResolution.shared.Money].\n\nFurther notes:\n\n- `id` must be non-empty\n  and stable\n- see [ListGizmos] for collections",
+        "tags" : [ "CatalogService" ],
+        "parameters" : [ {
+          "name" : "id",
+          "in" : "path",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "OK",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/Gizmo"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/gizmos" : {
+      "get" : {
+        "summary" : "Lists every [Gizmo] in the catalog.",
+        "description" : "Pages through [Gizmo] results; see [GetGizmo] for one.",
+        "tags" : [ "CatalogService" ],
+        "parameters" : [ {
+          "name" : "pageSize",
+          "in" : "query",
+          "description" : "At most 100 [Gizmo] items.",
+          "required" : false,
+          "schema" : {
+            "type" : "integer",
+            "format" : "int32",
+            "title" : "Page size"
+          }
+        }, {
+          "name" : "filter",
+          "in" : "query",
+          "description" : "Deliberately broken reference: [NoSuchThing].",
+          "required" : false,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "OK",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/ListGizmosResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "tags" : [ {
+    "name" : "CatalogService",
+    "description" : "Manages [Gizmo] resources.  Fetch one with [GetGizmo]; on failure, details are in\n[Status.details][google.rpc.Status].\n\nUnmapped RPCs like [CatalogService.Reindex] have no operation, and imported types like\n[engine.protoc.openapi.example.referenceLinkResolution.shared.Money] have no schema here, so both render as code."
+  } ],
+  "components" : {
+    "schemas" : {
+      "Gadget" : {
+        "type" : "object",
+        "description" : "A catalog gadget.  The bare name [Gadget] is ambiguous with [engine.protoc.openapi.example.referenceLinkResolution.shared.Gadget].",
+        "properties" : {
+          "id" : {
+            "type" : "string",
+            "description" : "Gadget id."
+          }
+        }
+      },
+      "Gizmo" : {
+        "type" : "object",
+        "description" : "A gizmo.  Its label is [name]; its state is a [GizmoState].\n\n`id` is the stable identifier.",
+        "properties" : {
+          "id" : {
+            "type" : "string",
+            "description" : "Unique id."
+          },
+          "name" : {
+            "type" : "string",
+            "description" : "Human-readable label."
+          },
+          "state" : {
+            "$ref" : "#/components/schemas/GizmoState",
+            "description" : "Lifecycle state, one of the [GizmoState] values such as [GIZMO_STATE_ACTIVE]."
+          },
+          "gadget" : {
+            "$ref" : "#/components/schemas/Gadget",
+            "description" : "The gizmo's gadget."
+          }
+        }
+      },
+      "GizmoState" : {
+        "type" : "string",
+        "description" : "Lifecycle state of a \\[Gizmo\\].\n\n- `GIZMO_STATE_UNSPECIFIED` — Unset.\n\n- `GIZMO_STATE_ACTIVE` — Visible; see \\[GIZMO\\_STATE\\_RETIRED\\] for the end state.\n\n- `GIZMO_STATE_RETIRED` — No longer offered.",
+        "enum" : [ "GIZMO_STATE_UNSPECIFIED", "GIZMO_STATE_ACTIVE", "GIZMO_STATE_RETIRED" ]
+      },
+      "ListGizmosResponse" : {
+        "type" : "object",
+        "description" : "A page of [Gizmo] results.",
+        "properties" : {
+          "gizmos" : {
+            "type" : "array",
+            "items" : {
+              "$ref" : "#/components/schemas/Gizmo"
+            },
+            "description" : "The items on this page."
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/examples/src/referenceLinkResolution/resources/redoc.openapi.json b/examples/src/referenceLinkResolution/resources/redoc.openapi.json
new file mode 100644
index 0000000..4ef2904
--- /dev/null
+++ b/examples/src/referenceLinkResolution/resources/redoc.openapi.json
@@ -0,0 +1,149 @@
+{
+  "openapi" : "3.1.0",
+  "paths" : {
+    "/gizmos/{id}" : {
+      "get" : {
+        "summary" : "Gets a single Gizmo by GetGizmoRequest.id.",
+        "description" : "Gets a single [Gizmo](#tag/Gizmo) by `GetGizmoRequest.id`.  Its price is a `engine.protoc.openapi.example.referenceLinkResolution.shared.Money`.\n\nFurther notes:\n\n- `id` must be non-empty\n  and stable\n- see [ListGizmos](#operation/CatalogService_ListGizmos) for collections",
+        "operationId" : "CatalogService_GetGizmo",
+        "tags" : [ "CatalogService" ],
+        "parameters" : [ {
+          "name" : "id",
+          "in" : "path",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "OK",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/Gizmo"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/gizmos" : {
+      "get" : {
+        "summary" : "Lists every Gizmo in the catalog.",
+        "description" : "Pages through [Gizmo](#tag/Gizmo) results; see [GetGizmo](#operation/CatalogService_GetGizmo) for one.",
+        "operationId" : "CatalogService_ListGizmos",
+        "tags" : [ "CatalogService" ],
+        "parameters" : [ {
+          "name" : "pageSize",
+          "in" : "query",
+          "description" : "At most 100 [Gizmo](#tag/Gizmo) items.",
+          "required" : false,
+          "schema" : {
+            "type" : "integer",
+            "format" : "int32",
+            "title" : "Page size"
+          }
+        }, {
+          "name" : "filter",
+          "in" : "query",
+          "description" : "Deliberately broken reference: `NoSuchThing`.",
+          "required" : false,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "OK",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/ListGizmosResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "tags" : [ {
+    "name" : "CatalogService",
+    "description" : "Manages [Gizmo](#tag/Gizmo) resources.  Fetch one with [GetGizmo](#operation/CatalogService_GetGizmo); on failure, details are in\n[Status.details](https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status).\n\nUnmapped RPCs like `CatalogService.Reindex` have no operation, and imported types like\n`engine.protoc.openapi.example.referenceLinkResolution.shared.Money` have no schema here, so both render as code."
+  }, {
+    "name" : "Gadget",
+    "description" : "<SchemaDefinition schemaRef=\"#/components/schemas/Gadget\" />"
+  }, {
+    "name" : "Gizmo",
+    "description" : "<SchemaDefinition schemaRef=\"#/components/schemas/Gizmo\" />"
+  }, {
+    "name" : "GizmoState",
+    "description" : "<SchemaDefinition schemaRef=\"#/components/schemas/GizmoState\" />"
+  }, {
+    "name" : "ListGizmosResponse",
+    "description" : "<SchemaDefinition schemaRef=\"#/components/schemas/ListGizmosResponse\" />"
+  } ],
+  "components" : {
+    "schemas" : {
+      "Gadget" : {
+        "type" : "object",
+        "description" : "A catalog gadget.  The bare name [Gadget](#tag/Gadget) is ambiguous with `engine.protoc.openapi.example.referenceLinkResolution.shared.Gadget`.",
+        "properties" : {
+          "id" : {
+            "type" : "string",
+            "description" : "Gadget id."
+          }
+        }
+      },
+      "Gizmo" : {
+        "type" : "object",
+        "description" : "A gizmo.  Its label is [name](#tag/Gizmo); its state is a [GizmoState](#tag/GizmoState).\n\n`id` is the stable identifier.",
+        "properties" : {
+          "id" : {
+            "type" : "string",
+            "description" : "Unique id."
+          },
+          "name" : {
+            "type" : "string",
+            "description" : "Human-readable label."
+          },
+          "state" : {
+            "$ref" : "#/components/schemas/GizmoState",
+            "description" : "Lifecycle state, one of the [GizmoState](#tag/GizmoState) values such as [GIZMO\\_STATE\\_ACTIVE](#tag/GizmoState)."
+          },
+          "gadget" : {
+            "$ref" : "#/components/schemas/Gadget",
+            "description" : "The gizmo's gadget."
+          }
+        }
+      },
+      "GizmoState" : {
+        "type" : "string",
+        "description" : "Lifecycle state of a [Gizmo](#tag/Gizmo).\n\n- `GIZMO_STATE_UNSPECIFIED` — Unset.\n\n- `GIZMO_STATE_ACTIVE` — Visible; see [GIZMO\\_STATE\\_RETIRED](#tag/GizmoState) for the end state.\n\n- `GIZMO_STATE_RETIRED` — No longer offered.",
+        "enum" : [ "GIZMO_STATE_UNSPECIFIED", "GIZMO_STATE_ACTIVE", "GIZMO_STATE_RETIRED" ]
+      },
+      "ListGizmosResponse" : {
+        "type" : "object",
+        "description" : "A page of [Gizmo](#tag/Gizmo) results.",
+        "properties" : {
+          "gizmos" : {
+            "type" : "array",
+            "items" : {
+              "$ref" : "#/components/schemas/Gizmo"
+            },
+            "description" : "The items on this page."
+          }
+        }
+      }
+    }
+  },
+  "x-tagGroups" : [ {
+    "name" : "API",
+    "tags" : [ "CatalogService" ]
+  }, {
+    "name" : "Schemas",
+    "tags" : [ "Gadget", "Gizmo", "GizmoState", "ListGizmosResponse" ]
+  } ]
+}
diff --git a/examples/src/referenceLinkResolution/resources/swagger.openapi.json b/examples/src/referenceLinkResolution/resources/swagger.openapi.json
new file mode 100644
index 0000000..add7af8
--- /dev/null
+++ b/examples/src/referenceLinkResolution/resources/swagger.openapi.json
@@ -0,0 +1,130 @@
+{
+  "openapi" : "3.1.0",
+  "paths" : {
+    "/gizmos/{id}" : {
+      "get" : {
+        "summary" : "Gets a single Gizmo by GetGizmoRequest.id.",
+        "description" : "Gets a single `Gizmo` by `GetGizmoRequest.id`.  Its price is a `engine.protoc.openapi.example.referenceLinkResolution.shared.Money`.\n\nFurther notes:\n\n- `id` must be non-empty\n  and stable\n- see [ListGizmos](#/CatalogService/CatalogService_ListGizmos) for collections",
+        "operationId" : "CatalogService_GetGizmo",
+        "tags" : [ "CatalogService" ],
+        "parameters" : [ {
+          "name" : "id",
+          "in" : "path",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "OK",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/Gizmo"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/gizmos" : {
+      "get" : {
+        "summary" : "Lists every Gizmo in the catalog.",
+        "description" : "Pages through `Gizmo` results; see [GetGizmo](#/CatalogService/CatalogService_GetGizmo) for one.",
+        "operationId" : "CatalogService_ListGizmos",
+        "tags" : [ "CatalogService" ],
+        "parameters" : [ {
+          "name" : "pageSize",
+          "in" : "query",
+          "description" : "At most 100 `Gizmo` items.",
+          "required" : false,
+          "schema" : {
+            "type" : "integer",
+            "format" : "int32",
+            "title" : "Page size"
+          }
+        }, {
+          "name" : "filter",
+          "in" : "query",
+          "description" : "Deliberately broken reference: `NoSuchThing`.",
+          "required" : false,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "OK",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/ListGizmosResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "tags" : [ {
+    "name" : "CatalogService",
+    "description" : "Manages `Gizmo` resources.  Fetch one with [GetGizmo](#/CatalogService/CatalogService_GetGizmo); on failure, details are in\n[Status.details](https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status).\n\nUnmapped RPCs like `CatalogService.Reindex` have no operation, and imported types like\n`engine.protoc.openapi.example.referenceLinkResolution.shared.Money` have no schema here, so both render as code."
+  } ],
+  "components" : {
+    "schemas" : {
+      "Gadget" : {
+        "type" : "object",
+        "description" : "A catalog gadget.  The bare name `Gadget` is ambiguous with `engine.protoc.openapi.example.referenceLinkResolution.shared.Gadget`.",
+        "properties" : {
+          "id" : {
+            "type" : "string",
+            "description" : "Gadget id."
+          }
+        }
+      },
+      "Gizmo" : {
+        "type" : "object",
+        "description" : "A gizmo.  Its label is `name`; its state is a `GizmoState`.\n\n`id` is the stable identifier.",
+        "properties" : {
+          "id" : {
+            "type" : "string",
+            "description" : "Unique id."
+          },
+          "name" : {
+            "type" : "string",
+            "description" : "Human-readable label."
+          },
+          "state" : {
+            "$ref" : "#/components/schemas/GizmoState",
+            "description" : "Lifecycle state, one of the `GizmoState` values such as `GIZMO_STATE_ACTIVE`."
+          },
+          "gadget" : {
+            "$ref" : "#/components/schemas/Gadget",
+            "description" : "The gizmo's gadget."
+          }
+        }
+      },
+      "GizmoState" : {
+        "type" : "string",
+        "description" : "Lifecycle state of a `Gizmo`.\n\n- `GIZMO_STATE_UNSPECIFIED` — Unset.\n\n- `GIZMO_STATE_ACTIVE` — Visible; see `GIZMO_STATE_RETIRED` for the end state.\n\n- `GIZMO_STATE_RETIRED` — No longer offered.",
+        "enum" : [ "GIZMO_STATE_UNSPECIFIED", "GIZMO_STATE_ACTIVE", "GIZMO_STATE_RETIRED" ]
+      },
+      "ListGizmosResponse" : {
+        "type" : "object",
+        "description" : "A page of `Gizmo` results.",
+        "properties" : {
+          "gizmos" : {
+            "type" : "array",
+            "items" : {
+              "$ref" : "#/components/schemas/Gizmo"
+            },
+            "description" : "The items on this page."
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/examples/src/referenceLinks/README.md b/examples/src/referenceLinks/README.md
index 68be300..6ec4e5c 100644
--- a/examples/src/referenceLinks/README.md
+++ b/examples/src/referenceLinks/README.md
@@ -3,9 +3,10 @@
 Demonstrates the `referenceLinkTarget` option, which rewrites CommonMark reference links in proto comments into same-document anchors.
 
 A reference link is a bracketed token in a leading comment — `[Widget]`, `[catalog.v1.Widget]`, or `[WidgetService.GetWidget]` — that names another element in the compile scope.
-When it resolves, the plugin replaces it with a Markdown link to the referenced operation, tag, or schema; when it does not, the bracketed text is left as-is and a warning is logged.
+When it resolves, the plugin replaces it with a Markdown link to the referenced operation, tag, or schema, or with an inline code span when the target has no anchor in the document.
+What happens to references that don't resolve is controlled by `resolveReferenceLinksMode`; see [referenceLinkResolution](../referenceLinkResolution/README.md).
 
-Anchor fragment formats are renderer-specific and are not portable, so the target is chosen explicitly (resolution is off by default).
+Anchor fragment formats are renderer-specific and are not portable, so the target is chosen explicitly (the default, `NONE`, links nothing).
 This suite compiles the same proto twice:
 
 - **`SWAGGER_UI`** — operation references resolve to `#/{tag}/{operationId}` and service references to `#/{tag}`.
diff --git a/examples/src/serviceOrdering/resources/engine.protoc.openapi.example.serviceOrdering.openapi.json b/examples/src/serviceOrdering/resources/engine.protoc.openapi.example.serviceOrdering.openapi.json
index 8afe6bb..1e1bbef 100644
--- a/examples/src/serviceOrdering/resources/engine.protoc.openapi.example.serviceOrdering.openapi.json
+++ b/examples/src/serviceOrdering/resources/engine.protoc.openapi.example.serviceOrdering.openapi.json
@@ -133,16 +133,16 @@
   },
   "tags" : [ {
     "name" : "BetaService",
-    "description" : "Source-position 1 — explicit `index_order = -1` places it ahead of every un-annotated\n service.  Negative indices are intended for exactly this case."
+    "description" : "Source-position 1 — explicit `index_order = -1` places it ahead of every un-annotated\nservice.  Negative indices are intended for exactly this case."
   }, {
     "name" : "AlphaService",
     "description" : "Source-position 0 — no `index_order`, so it falls into its encounter ordinal (0)."
   }, {
     "name" : "EpsilonService",
-    "description" : "Source-position 4 — explicit `index_order = 0` collides with AlphaService's implicit\n ordinal of 0.  The compiler logs a WARN naming both services and falls back to source\n order; AlphaService keeps the earlier slot because it appears first in source."
+    "description" : "Source-position 4 — explicit `index_order = 0` collides with AlphaService's implicit\nordinal of 0.  The compiler logs a WARN naming both services and falls back to source\norder; AlphaService keeps the earlier slot because it appears first in source."
   }, {
     "name" : "GammaService",
-    "description" : "Source-position 2 — no annotation, so it sorts at ordinal 2.  Sparse: nothing fills the\n gap between Alpha (0) and Gamma (10) other than this one."
+    "description" : "Source-position 2 — no annotation, so it sorts at ordinal 2.  Sparse: nothing fills the\ngap between Alpha (0) and Gamma (10) other than this one."
   }, {
     "name" : "DeltaService",
     "description" : "Source-position 3 — explicit `index_order = 10` pushes it well past the un-annotated tail."
diff --git a/examples/src/version/resources/engine.protoc.openapi.example.version.PinnedVersionService.openapi.json b/examples/src/version/resources/engine.protoc.openapi.example.version.PinnedVersionService.openapi.json
index 6ff5db8..d9c7d7c 100644
--- a/examples/src/version/resources/engine.protoc.openapi.example.version.PinnedVersionService.openapi.json
+++ b/examples/src/version/resources/engine.protoc.openapi.example.version.PinnedVersionService.openapi.json
@@ -1,6 +1,6 @@
 {
   "info": {
-    "description": "A service whose API version is pinned by an explicit service-level engine annotation.\n Regardless of what options.version is set to, the annotation version always wins.",
+    "description": "A service whose API version is pinned by an explicit service-level engine annotation.\nRegardless of what options.version is set to, the annotation version always wins.",
     "title": "PinnedVersionService",
     "version": "pinned-1.0.0"
   },
diff --git a/examples/src/version/resources/engine.protoc.openapi.example.version.UnversionedService.openapi.json b/examples/src/version/resources/engine.protoc.openapi.example.version.UnversionedService.openapi.json
index 82844fe..c9c9f51 100644
--- a/examples/src/version/resources/engine.protoc.openapi.example.version.UnversionedService.openapi.json
+++ b/examples/src/version/resources/engine.protoc.openapi.example.version.UnversionedService.openapi.json
@@ -1,6 +1,6 @@
 {
   "info": {
-    "description": "A service with no version annotation.\n When options.version is set, the output receives that string as info.version.\n When options.version is absent, the output has no info.version at all.",
+    "description": "A service with no version annotation.\nWhen options.version is set, the output receives that string as info.version.\nWhen options.version is absent, the output has no info.version at all.",
     "title": "UnversionedService",
     "version": "global-2.0.0"
   },
diff --git a/examples/src/wellKnownTypes/resources/engine.protoc.openapi.example.wellKnownTypes.EnvelopeService.openapi.json b/examples/src/wellKnownTypes/resources/engine.protoc.openapi.example.wellKnownTypes.EnvelopeService.openapi.json
index 2787d88..314b66e 100644
--- a/examples/src/wellKnownTypes/resources/engine.protoc.openapi.example.wellKnownTypes.EnvelopeService.openapi.json
+++ b/examples/src/wellKnownTypes/resources/engine.protoc.openapi.example.wellKnownTypes.EnvelopeService.openapi.json
@@ -30,7 +30,7 @@
     "/envelopes/{id}/blob" : {
       "get" : {
         "summary" : "Returns a binary blob via google.api.HttpBody.",
-        "description" : "Returns a binary blob via google.api.HttpBody.  HttpBody itself becomes a\n component schema whose `extensions` field is `repeated google.protobuf.Any` —\n the regression that motivated the inline-WKT fix.",
+        "description" : "Returns a binary blob via google.api.HttpBody.  HttpBody itself becomes a\ncomponent schema whose `extensions` field is `repeated google.protobuf.Any` —\nthe regression that motivated the inline-WKT fix.",
         "parameters" : [ {
           "name" : "id",
           "in" : "path",
@@ -62,7 +62,7 @@
     "schemas" : {
       "Envelope" : {
         "type" : "object",
-        "description" : "Carries a structural well-known type at every field position so the generated\n component schema exercises the inline-WKT code path for each one.",
+        "description" : "Carries a structural well-known type at every field position so the generated\ncomponent schema exercises the inline-WKT code path for each one.",
         "properties" : {
           "id" : {
             "type" : "string",
@@ -100,7 +100,7 @@
       },
       "HttpBody" : {
         "type" : "object",
-        "description" : "Message that represents an arbitrary HTTP body. It should only be used for\n payload formats that can't be represented as JSON, such as raw binary or\n an HTML page.\n\n\n This message can be used both in streaming and non-streaming API methods in\n the request as well as the response.\n\n It can be used as a top-level request field, which is convenient if one\n wants to extract parameters from either the URL or HTTP template into the\n request fields and also want access to the raw HTTP body.\n\n Example:\n\n     message GetResourceRequest {\n       // A unique request id.\n       string request_id = 1;\n\n       // The raw HTTP body is bound to this field.\n       google.api.HttpBody http_body = 2;\n\n     }\n\n     service ResourceService {\n       rpc GetResource(GetResourceRequest)\n         returns (google.api.HttpBody);\n       rpc UpdateResource(google.api.HttpBody)\n         returns (google.protobuf.Empty);\n\n     }\n\n Example with streaming methods:\n\n     service CaldavService {\n       rpc GetCalendar(stream google.api.HttpBody)\n         returns (stream google.api.HttpBody);\n       rpc UpdateCalendar(stream google.api.HttpBody)\n         returns (stream google.api.HttpBody);\n\n     }\n\n Use of this type only changes how the request and response bodies are\n handled, all other features will continue to work unchanged.",
+        "description" : "Message that represents an arbitrary HTTP body. It should only be used for\npayload formats that can't be represented as JSON, such as raw binary or\nan HTML page.\n\n\nThis message can be used both in streaming and non-streaming API methods in\nthe request as well as the response.\n\nIt can be used as a top-level request field, which is convenient if one\nwants to extract parameters from either the URL or HTTP template into the\nrequest fields and also want access to the raw HTTP body.\n\nExample:\n\n    message GetResourceRequest {\n      // A unique request id.\n      string request_id = 1;\n\n      // The raw HTTP body is bound to this field.\n      google.api.HttpBody http_body = 2;\n\n    }\n\n    service ResourceService {\n      rpc GetResource(GetResourceRequest)\n        returns (google.api.HttpBody);\n      rpc UpdateResource(google.api.HttpBody)\n        returns (google.protobuf.Empty);\n\n    }\n\nExample with streaming methods:\n\n    service CaldavService {\n      rpc GetCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n      rpc UpdateCalendar(stream google.api.HttpBody)\n        returns (stream google.api.HttpBody);\n\n    }\n\nUse of this type only changes how the request and response bodies are\nhandled, all other features will continue to work unchanged.",
         "properties" : {
           "contentType" : {
             "type" : "string",
@@ -117,7 +117,7 @@
               "type" : "object",
               "additionalProperties" : true
             },
-            "description" : "Application specific response metadata. Must be set in the first response\n for streaming APIs."
+            "description" : "Application specific response metadata. Must be set in the first response\nfor streaming APIs."
           }
         }
       }
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 49ee9b9..41d6d35 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -11,7 +11,7 @@ grpcKotlin = "1.5.0"
 kotlinx-coroutines = "1.11.0"
 testcontainers = "2.0.5"
 kotest = "6.2.5"
-engine-protoc-utils = "1.0.3"
+engine-protoc-utils = "1.1.0"
 graalvm-sdk = "23.1.2"
 log4j = "2.26.1"
 
@@ -35,6 +35,7 @@ license-report = { id = "com.github.jk1.dependency-license-report", version.ref
 [libraries]
 commonmark = { group = "org.commonmark", name = "commonmark", version.ref = "commonmark" }
 engine-protoc-utils = { group = "com.engine", name = "protoc-utils", version.ref = "engine-protoc-utils" }
+engine-protoc-utils-markdown = { group = "com.engine", name = "protoc-utils-markdown", version.ref = "engine-protoc-utils" }
 graalvm-sdk = { group = "org.graalvm.sdk", name = "graal-sdk", version.ref = "graalvm-sdk" }
 google-api-grpc-googleCommonProtos = { group = "com.google.api.grpc", name = "proto-google-common-protos", version.ref = "google-common-protos" }
 jackson-databind = { group = "tools.jackson.core", name = "jackson-databind", version.ref = "jackson-core" }
diff --git a/src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt b/src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt
index 06e1ec0..5a8d698 100644
--- a/src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt
+++ b/src/main/kotlin/com/engine/protoc/openapi/ProtocGenOpenAPI.kt
@@ -4,6 +4,8 @@ import com.engine.protoc.openapi.compile.Compiler
 import com.engine.protoc.util.compiler.CodeGeneratorRequestWrapper
 import com.engine.protoc.util.compiler.Parameters
 import com.engine.protoc.util.extensions.wrap
+import com.engine.protoc.util.markdown.ReferenceLinkMode
+import com.engine.protoc.util.markdown.ReferenceLinkProcessor
 import com.google.api.AnnotationsProto
 import com.google.protobuf.ExtensionRegistry
 import com.google.protobuf.compiler.PluginProtos
@@ -408,21 +410,22 @@ public class ProtocGenOpenAPI(
         val serviceExclude: String?,
 
         /**
-         * Selects the documentation-renderer dialect that CommonMark **reference links** in
-         * `description` fields resolve against.  A reference link is a bracketed token such as
-         * `[Widget]`, `[catalog.v1.Widget]`, or `[WidgetService.GetWidget]` written in a proto
-         * leading comment; when it resolves, it is rewritten to a same-document anchor pointing at
-         * the referenced operation, tag, or schema.
+         * Selects the documentation-renderer dialect that resolved CommonMark **reference links**
+         * link to.  A reference link is a bracketed token such as `[Widget]`,
+         * `[catalog.v1.Widget]`, or `[WidgetService.GetWidget]` written in a proto comment or an
+         * annotation description; whether it is resolved, and what happens when it can't be, is
+         * controlled by [resolveReferenceLinksMode].  A resolved reference is rewritten to a
+         * same-document anchor pointing at the referenced operation, tag, or schema, or, when the
+         * target cannot address the element, to an inline code span (e.g. `` `Widget` ``).
          *
          * Anchor fragment formats are renderer-specific and **not** portable, so the target must be
-         * chosen explicitly; resolution is off by default:
+         * chosen explicitly:
          *
-         * - [ReferenceLinkTarget.NONE] (default) — reference-link resolution is disabled.
-         *   `description` fields still emit clean CommonMark, but bracketed tokens are left
-         *   untouched and no derived `operationId` is added.
+         * - [ReferenceLinkTarget.NONE] (default) — nothing is linked: resolved references render
+         *   as inline code spans, and no derived `operationId` is added.
          * - [ReferenceLinkTarget.SWAGGER_UI] — operations resolve to `#/{tag}/{operationId}`
          *   and services (tags) to `#/{tag}`.  Swagger UI has no stable anchor for component
-         *   schemas, so message/enum references cannot be linked (see the unresolved behaviour below).
+         *   schemas, so message/enum references render as inline code spans.
          *   Requires the consumer to enable Swagger UI's `deepLinking` option.
          * - [ReferenceLinkTarget.REDOC] — operations resolve to `#operation/{operationId}`, tags to
          *   `#tag/{tagName}`, and message/enum references to plugin-generated schema sections (see
@@ -431,13 +434,51 @@ public class ProtocGenOpenAPI(
          *   `x-tagGroups` "Schemas" group, so every schema reference has a controlled `#tag/{name}`
          *   anchor to point at.
          *
-         * Unresolved or non-portable references never fail the build: the brackets are stripped and
-         * the label is rendered as an inline code span (e.g. `[Property]` → `` `Property` ``) with a
-         * warning.  (In a derived `summary`, which is plain text, the label is emitted bare.)
+         * Elements that exist in the compile scope but have no anchor in this document — an RPC
+         * without an HTTP binding, a service that contributes no tag, a type that isn't emitted
+         * to `components/schemas` — also render as inline code spans; they are not failures.
+         * In plain-text fields (`summary`, `title`) references are emitted as bare text.
          *
          * Passed via `--openapi_out=referenceLinkTarget=redoc:outdir` (case-insensitive).
          */
         val referenceLinkTarget: ReferenceLinkTarget,
+
+        /**
+         * Controls resolution of CommonMark reference links (`[Widget]`, `[Widget.name]`,
+         * `[WidgetService.GetWidget]`, `[display text][Widget]`) in every string the plugin emits:
+         * proto comments and annotation-supplied descriptions, summaries, and titles.
+         *
+         * References resolve against every message, field, enum, enum value, service, and RPC in
+         * the request (including imported files), with bare names resolving first against the
+         * members of the commented descriptor.  Labels configured with [referenceLink] resolve to
+         * their URL first.
+         *
+         * - [ReferenceLinkMode.NONE] — references are not resolved; text is emitted as written,
+         *   brackets included.
+         * - [ReferenceLinkMode.WARN] — references are resolved; each unresolved or ambiguous
+         *   reference logs at `warn` and an unresolved one renders as an inline code span.
+         * - [ReferenceLinkMode.FAIL_ON_INVALID] (default) — as [ReferenceLinkMode.WARN], but each
+         *   failure logs at `error` and is collected; at the end of compilation the plugin sets
+         *   `CodeGeneratorResponse.error` listing every failure, so protoc fails the run.
+         *
+         * Passed via `--openapi_out=resolveReferenceLinksMode=warn:outdir` (case-insensitive).
+         */
+        val resolveReferenceLinksMode: ReferenceLinkMode,
+
+        /**
+         * Maps reference-link labels to URLs, so references to elements outside the compile scope
+         * can link to external documentation, e.g.
+         * `referenceLink=google.rpc.Status=https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status`
+         * makes `[Status.details][google.rpc.Status]` a link.  Repeat the parameter for each label.
+         * An override wins over any element of the same name in the compile scope.
+         *
+         * protoc splits `--openapi_out` parameters from the output directory at a `:`, so a URL
+         * scheme can't be written there; a URL that has no scheme and doesn't start with `/`,
+         * `#`, or `.` is treated as `https://`, e.g. `referenceLink=google.rpc.Status=cloud.google.com/...`.
+         *
+         * Passed via `--openapi_out=referenceLink=<label>=<URL>:outdir`.
+         */
+        val referenceLink: Map<String, String>,
     ) {
         /**
          * The serialization format for generated OpenAPI documents.
@@ -732,11 +773,34 @@ public class ProtocGenOpenAPI(
             public var referenceLinkTarget: ReferenceLinkTarget =
                 parameters.get<ReferenceLinkTarget>("referenceLinkTarget") ?: ReferenceLinkTarget.NONE
 
+            /**
+             * @see [Options.resolveReferenceLinksMode]
+             */
+            public var resolveReferenceLinksMode: ReferenceLinkMode =
+                parameters.get<ReferenceLinkMode>("resolveReferenceLinksMode") ?: ReferenceLinkMode.FAIL_ON_INVALID
+
+            /**
+             * @see [Options.referenceLink]
+             */
+            public var referenceLink: Map<String, String> =
+                ReferenceLinkProcessor.parseOverrides(parameters.get<List<String>>("referenceLink"))
+                    .mapValues { (_, url) -> withDefaultScheme(url) }
+
             public companion object {
                 private const val SERVICE_INCLUDE_DEFAULT =
                     """^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)*$"""
 
                 public fun from(parameters: Parameters): Builder = Builder(parameters)
+
+                private val schemePattern = Regex("^[a-zA-Z][a-zA-Z0-9+.-]*:")
+
+                /** Prepends `https://` to a URL with no scheme that isn't a relative or fragment reference. */
+                private fun withDefaultScheme(url: String): String =
+                    if (schemePattern.containsMatchIn(url) || url.startsWith("/") || url.startsWith("#") || url.startsWith(".")) {
+                        url
+                    } else {
+                        "https://$url"
+                    }
             }
 
             public fun build(): Options =
@@ -768,6 +832,8 @@ public class ProtocGenOpenAPI(
                     serviceInclude = serviceInclude,
                     serviceExclude = serviceExclude,
                     referenceLinkTarget = referenceLinkTarget,
+                    resolveReferenceLinksMode = resolveReferenceLinksMode,
+                    referenceLink = referenceLink,
                 )
         }
     }
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/Compiler.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/Compiler.kt
index 36ea4ef..56c0ae7 100644
--- a/src/main/kotlin/com/engine/protoc/openapi/compile/Compiler.kt
+++ b/src/main/kotlin/com/engine/protoc/openapi/compile/Compiler.kt
@@ -8,7 +8,9 @@ import com.engine.protoc.openapi.compile.json.mergeInto
 import com.engine.protoc.util.compiler.CodeGeneratorRequestWrapper
 import com.engine.protoc.util.compiler.CodeGeneratorResponseWrapper
 import com.engine.protoc.util.file.FileDescriptorProtoWrapper
+import com.engine.protoc.util.markdown.ReferenceLinkFailure
 import com.engine.protoc.util.service.ServiceDescriptorProtoWrapper
+import com.google.api.AnnotationsProto
 import com.google.protobuf.compiler.PluginProtos
 import com.networknt.schema.InputFormat
 import com.networknt.schema.SchemaLocation
@@ -152,18 +154,6 @@ internal class Compiler(
         // that explicitly sets info.version will overwrite it (higher-priority layers win).
         applyOptionsVersion(doc, ctx)
 
-        for (file in targetFiles) {
-            try {
-                val extension = file.options?.findExtension(Annotations.file)?.value
-                    ?.takeIf { it.hasOpenapi() }?.openapi ?: continue
-                extension.mergeInto(doc, ctx)
-            } catch (e: Exception) {
-                val msg = "[${file.name}] Error merging OpenAPI extension: ${e.detail()}"
-                log.error(msg, e)
-                response.addError(msg)
-            }
-        }
-
         val collector = MessageCollector(ctx.messageIndex, ctx.enumIndex, options.inlineEnums)
         val pathsBuilder = PathsBuilder(
             ctx,
@@ -172,7 +162,6 @@ internal class Compiler(
             options.autoMapping,
             options.inlineRequestSchemas,
             options.inlineResponseSchemas,
-            referenceLinkResolverFor(targetFiles, ctx),
             collectComponentParameterNames(targetFiles),
         )
 
@@ -189,6 +178,25 @@ internal class Compiler(
             }
         }
 
+        ctx.descriptions.beginDocument(
+            isSchemaEmitted = { it in collector.allCollected },
+            isServiceEmitted = { serviceFqn -> targetFiles.any { file -> file.emitsService(serviceFqn) } },
+        )
+
+        // File-level annotations are merged after the seed pass so reference links in their
+        // descriptions see the document's final set of component schemas.
+        for (file in targetFiles) {
+            try {
+                val extension = file.options?.findExtension(Annotations.file)?.value
+                    ?.takeIf { it.hasOpenapi() }?.openapi ?: continue
+                extension.mergeInto(doc, ctx)
+            } catch (e: Exception) {
+                val msg = "[${file.name}] Error merging OpenAPI extension: ${e.detail()}"
+                log.error(msg, e)
+                response.addError(msg)
+            }
+        }
+
         // Build all targetFiles in a single call so that services with
         // `(engine.protoc.openapi.index_order)` can be sorted across file boundaries — the
         // per-file fallback ordinal in PathsBuilder.orderByIndex is computed against this
@@ -218,6 +226,7 @@ internal class Compiler(
 
         ctx.schemaKeyResolver.rewriteRefs(doc)
         emitRedocSchemaSections(doc, ctx)
+        reportReferenceLinkFailures(response, ctx)
 
         if (!response.hasErrors) {
             try {
@@ -271,6 +280,7 @@ internal class Compiler(
                     }
                     // Apply options version before the annotation so the annotation can override it.
                     applyOptionsVersion(doc, ctx)
+                    ctx.descriptions.beginDocument(isSchemaEmitted = { false }, isServiceEmitted = { false })
                     fileAnnotation.mergeInto(doc, ctx)
                     val pkg = file.`package`?.value.orEmpty()
                     val fileName =
@@ -293,23 +303,8 @@ internal class Compiler(
                         it.set("paths", ctx.obj())
                     }
 
-                    // Layer 1: attributes derived from the service itself (lowest priority)
-                    applyServiceDerivedAttributes(doc, service, ctx)
-
-                    // Layer 2: options-provided version as a global default.
-                    // Applied after service-derived attributes (which never set info.version) and
-                    // before annotation layers so that annotations can override it.
-                    applyOptionsVersion(doc, ctx)
-
-                    // Layer 3: file-level annotation overwrites derived values
-                    fileAnnotation?.mergeInto(doc, ctx)
-
-                    // Layer 4: explicit service-level annotation (highest priority)
-                    service.options?.findExtension(Annotations.service)?.value
-                        ?.takeIf { it.hasOpenapi() }?.openapi
-                        ?.mergeInto(doc, ctx)
-
-                    // Paths — only this service's methods
+                    // Seed this service's schemas first so reference links in every layer below
+                    // see the document's final set of component schemas.
                     val collector = MessageCollector(ctx.messageIndex, ctx.enumIndex, options.inlineEnums)
                     val pathsBuilder = PathsBuilder(
                         ctx,
@@ -318,10 +313,34 @@ internal class Compiler(
                         options.autoMapping,
                         options.inlineRequestSchemas,
                         options.inlineResponseSchemas,
-                        referenceLinkResolverFor(listOf(file), ctx),
                         componentParameterNames,
                     )
                     pathsBuilder.seedForService(service, file.`package`?.value)
+                    val serviceFqn = listOfNotNull(file.`package`?.value?.ifEmpty { null }, service.name?.value).joinToString(".")
+                    ctx.descriptions.beginDocument(
+                        isSchemaEmitted = { it in collector.allCollected },
+                        isServiceEmitted = { it == serviceFqn && file.emitsService(serviceFqn) },
+                    )
+
+                    // Layer 1: attributes derived from the service itself (lowest priority)
+                    applyServiceDerivedAttributes(doc, file, service, ctx)
+
+                    // Layer 2: options-provided version as a global default.
+                    // Applied after service-derived attributes (which never set info.version) and
+                    // before annotation layers so that annotations can override it.
+                    applyOptionsVersion(doc, ctx)
+
+                    ctx.descriptions.withDefaultScope(serviceFqn) {
+                        // Layer 3: file-level annotation overwrites derived values
+                        fileAnnotation?.mergeInto(doc, ctx)
+
+                        // Layer 4: explicit service-level annotation (highest priority)
+                        service.options?.findExtension(Annotations.service)?.value
+                            ?.takeIf { it.hasOpenapi() }?.openapi
+                            ?.mergeInto(doc, ctx)
+                    }
+
+                    // Paths — only this service's methods
                     mergePaths(doc, pathsBuilder.buildForService(service, file.`package`?.value), ctx)
 
                     applyServiceTags(doc, pathsBuilder, ctx)
@@ -361,6 +380,8 @@ internal class Compiler(
             }
         }
 
+        reportReferenceLinkFailures(response, ctx)
+
         return response.build()
     }
 
@@ -369,25 +390,32 @@ internal class Compiler(
     // -------------------------------------------------------------------------
 
     /**
-     * Builds the reference-link resolver for a document spanning [files], or `null` when
-     * `referenceLinkTarget = NONE`.  The resolver indexes those files' schemas, services, and
-     * operations so CommonMark reference links in `description` fields rewrite to anchors.
+     * True when the service [serviceFqn] is declared in this file, passes the service filters, and
+     * has at least one RPC that becomes an operation — i.e. its tag and operations exist in the
+     * document.
      */
-    private fun referenceLinkResolverFor(
-        files: List<FileDescriptorProtoWrapper>,
+    private fun FileDescriptorProtoWrapper.emitsService(serviceFqn: String): Boolean {
+        val pkg = `package`?.value
+        val service = services.find { listOfNotNull(pkg?.ifEmpty { null }, it.name?.value).joinToString(".") == serviceFqn }
+            ?: return false
+        return isServiceIncluded(pkg, service) &&
+            service.methods.any { this@Compiler.options.autoMapping || it.options?.findExtension(AnnotationsProto.http)?.value != null }
+    }
+
+    /**
+     * Adds every reference-link failure collected while building the document to [response], so
+     * protoc fails the run under `resolveReferenceLinksMode=FAIL_ON_INVALID`.
+     */
+    private fun reportReferenceLinkFailures(
+        response: CodeGeneratorResponseWrapper,
         ctx: JsonContext,
-    ): ReferenceLinkResolver? =
-        if (options.referenceLinkTarget == ProtocGenOpenAPI.Options.ReferenceLinkTarget.NONE) {
-            null
-        } else {
-            ReferenceLinkResolver(
-                files,
-                options.referenceLinkTarget,
-                options.autoTagServices,
-                options.autoMapping,
-                ctx.schemaKeyResolver,
-            )
-        }
+    ) {
+        val failures = ctx.descriptions.drainFailures().distinct()
+        if (failures.isEmpty()) return
+        val summary = ReferenceLinkFailure.summary(failures)
+        log.error("protoc-gen-openapi failed:\n{}", summary)
+        response.addError("protoc-gen-openapi failed:\n$summary")
+    }
 
     /**
      * Under `referenceLinkTarget = REDOC`, gives every `components/schemas` entry an addressable
@@ -395,7 +423,7 @@ internal class Compiler(
      * standalone component schema, so for each schema we emit a top-level tag named after the
      * schema key whose description is a Redoc `<SchemaDefinition>` directive; Redoc renders that
      * tag as the schema's section, reachable at `#tag/{key}` — exactly the anchor
-     * [ReferenceLinkResolver] emits.
+     * [Descriptions] emits.
      *
      * When `autoTagServices` is enabled (so every operation already carries a service tag) we also
      * emit an `x-tagGroups` navigation split — operation/service tags under "API", schema sections
@@ -482,6 +510,7 @@ internal class Compiler(
             convertGrpcStatus = options.convertGrpcStatus,
             streamNewlineDelimited = options.streamNewlineDelimited,
             streamSseStyleDelimited = options.streamSseStyleDelimited,
+            descriptions = Descriptions(request.protoFiles, options, resolver),
         )
         val targetFiles = request.filesToGenerate.mapNotNull { name ->
             request.protoFiles.find { it.name == name }
@@ -584,14 +613,15 @@ internal class Compiler(
 
     private fun applyServiceDerivedAttributes(
         doc: ObjectNode,
+        file: FileDescriptorProtoWrapper,
         service: ServiceDescriptorProtoWrapper,
         ctx: JsonContext,
     ) {
         val infoNode = doc.get("info") as? ObjectNode
             ?: ctx.obj().also { doc.set("info", it) }
         service.name?.value?.let { infoNode.put("title", it) }
-        service.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-            ?.let { infoNode.put("description", it) }
+        val serviceFqn = listOfNotNull(file.`package`?.value?.ifEmpty { null }, service.name?.value).joinToString(".")
+        ctx.descriptions.comment(service)?.let { infoNode.put("description", ctx.descriptions.markdown(it, serviceFqn)) }
     }
 
     /**
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/Descriptions.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/Descriptions.kt
new file mode 100644
index 0000000..fefe952
--- /dev/null
+++ b/src/main/kotlin/com/engine/protoc/openapi/compile/Descriptions.kt
@@ -0,0 +1,237 @@
+package com.engine.protoc.openapi.compile
+
+import com.engine.protoc.openapi.Annotations
+import com.engine.protoc.openapi.ProtocGenOpenAPI
+import com.engine.protoc.openapi.ProtocGenOpenAPI.Options.ReferenceLinkTarget
+import com.engine.protoc.util.AbstractLocatable
+import com.engine.protoc.util.GeneratedMessageWrapper
+import com.engine.protoc.util.file.FileDescriptorProtoWrapper
+import com.engine.protoc.util.markdown.MarkdownText
+import com.engine.protoc.util.markdown.ReferenceElement
+import com.engine.protoc.util.markdown.ReferenceIndex
+import com.engine.protoc.util.markdown.ReferenceLinkFailure
+import com.engine.protoc.util.markdown.ReferenceLinkMode
+import com.engine.protoc.util.markdown.ReferenceLinkProcessor
+import com.engine.protoc.util.markdown.ReferenceRendering
+import com.engine.protoc.util.markdown.UnresolvedReferenceRendering
+import com.engine.protoc.util.service.MethodDescriptorProtoWrapper
+import com.engine.protoc.util.service.ServiceDescriptorProtoWrapper
+import com.google.api.AnnotationsProto
+import org.commonmark.node.Node
+import org.commonmark.parser.Parser
+import org.slf4j.LoggerFactory
+import java.util.IdentityHashMap
+
+private val log = LoggerFactory.getLogger(Descriptions::class.java)
+
+/**
+ * Produces every human-readable string the plugin emits, from proto comments and annotations.
+ *
+ * Strings fall into two kinds:
+ *
+ *  - **CommonMark** (`description` fields) — [markdown] resolves reference links (`[Widget]`,
+ *    `[WidgetService.GetWidget]`, `[text][google.rpc.Status]`) to anchors in the generated
+ *    document, to inline code spans for elements with no anchor, or to configured
+ *    `referenceLink` URLs.
+ *  - **Plain text** (`summary`, `title`, OAuth scope descriptions) — [plain] and [summary]
+ *    resolve references the same way, so bad references are still reported, then flatten the
+ *    Markdown to text.
+ *
+ * Failures are reported per `resolveReferenceLinksMode` and drained by the compiler with
+ * [drainFailures].  Anchors are only emitted for elements present in the document being built,
+ * which the compiler declares with [beginDocument].
+ */
+internal class Descriptions(
+    files: List<FileDescriptorProtoWrapper>,
+    private val options: ProtocGenOpenAPI.Options,
+    private val schemaKeyResolver: SchemaKeyResolver,
+) {
+    /** Where a reference to an element points in the OpenAPI document; equal targets are not ambiguous. */
+    sealed interface Target {
+        /** A message or enum, or a member of one — fields and enum values have no anchor of their own. */
+        data class Schema(val typeName: String) : Target
+
+        /** A service, addressable as its auto-generated tag. */
+        data class Tag(val serviceFqn: String, val name: String) : Target
+
+        /** An RPC, addressable as its operation when it has an HTTP binding (or `autoMapping` is on). */
+        data class Operation(val serviceFqn: String, val operationId: String, val primaryTag: String?, val mapped: Boolean) : Target
+    }
+
+    // Descriptor proto → FQN of the element, recorded while indexing, so callers can scope a
+    // comment by the descriptor that owns it.
+    private val fqnByDescriptor = IdentityHashMap<Any, String>()
+
+    private var isSchemaEmitted: (String) -> Boolean = { false }
+    private var isServiceEmitted: (String) -> Boolean = { false }
+    private var defaultScope: String = ""
+
+    private val processor: ReferenceLinkProcessor<Target> =
+        ReferenceLinkProcessor(
+            index = ReferenceIndex(files, targetFor = ::targetFor),
+            mode = options.resolveReferenceLinksMode,
+            overrides = options.referenceLink,
+            unresolvedRendering = UnresolvedReferenceRendering.CODE,
+            render = ::render,
+        )
+
+    private val parser: Parser = Parser.builder().linkProcessor(processor).build()
+
+    /**
+     * Declare the document about to be built: [isSchemaEmitted] tells whether a type (`.pkg.Msg`)
+     * is a `components/schemas` entry, and [isServiceEmitted] whether a service (`pkg.Svc`)
+     * contributes operations to it.
+     */
+    fun beginDocument(
+        isSchemaEmitted: (String) -> Boolean,
+        isServiceEmitted: (String) -> Boolean,
+    ) {
+        this.isSchemaEmitted = isSchemaEmitted
+        this.isServiceEmitted = isServiceEmitted
+    }
+
+    /**
+     * Run [block] with [scopeFqn] as the scope for strings that don't name their own, so
+     * annotation-supplied text resolves bare names against the annotated descriptor.
+     */
+    fun <R> withDefaultScope(
+        scopeFqn: String,
+        block: () -> R,
+    ): R {
+        val prior = defaultScope
+        defaultScope = scopeFqn
+        return try {
+            block()
+        } finally {
+            defaultScope = prior
+        }
+    }
+
+    /** The cleaned leading comment of [element], or `null` when it has none. */
+    fun comment(element: AbstractLocatable?): String? = element?.location?.leadingComments?.cleaned?.takeIf { it.isNotBlank() }
+
+    /**
+     * [text] as a CommonMark `description` with reference links resolved under [scopeFqn].  Text
+     * without references is returned unchanged; otherwise the document is re-rendered.
+     */
+    fun markdown(
+        text: String,
+        scopeFqn: String = defaultScope,
+    ): String {
+        if (options.resolveReferenceLinksMode == ReferenceLinkMode.NONE) return text
+        val document = parse(text, scopeFqn)
+        return if (processor.touched) MarkdownText.render(document) else text
+    }
+
+    /** [text] flattened to plain text for a field that can't hold Markdown, with references reported. */
+    fun plain(
+        text: String,
+        scopeFqn: String = defaultScope,
+    ): String = MarkdownText.toPlainText(parse(text, scopeFqn))
+
+    /** The first sentence of [text] as plain text, with references reported. */
+    fun summary(
+        text: String,
+        scopeFqn: String = defaultScope,
+    ): String = MarkdownText.firstSentence(parse(text, scopeFqn))
+
+    /** Parse [text] with reference links resolved under [scopeFqn]. */
+    fun parse(
+        text: String,
+        scopeFqn: String = defaultScope,
+    ): Node = processor.withScope(scopeFqn) { parser.parse(text) }
+
+    /** Return and clear the reference-link failures recorded under `FAIL_ON_INVALID`. */
+    fun drainFailures(): List<ReferenceLinkFailure> = processor.drainFailures()
+
+    /** The FQN (without a leading dot) of the element [descriptor] wraps, or `""` when it isn't indexed. */
+    fun scopeOf(descriptor: GeneratedMessageWrapper<*>?): String = descriptor?.let { fqnByDescriptor[it.proto] }.orEmpty()
+
+    /** True when resolved RPC references link to operations, which then need a stable `operationId`. */
+    val linksOperations: Boolean get() = options.referenceLinkTarget != ReferenceLinkTarget.NONE
+
+    private fun targetFor(element: ReferenceElement): Target {
+        fqnByDescriptor[element.descriptor.proto] = element.fqn
+        return when (element.kind) {
+            ReferenceElement.Kind.MESSAGE, ReferenceElement.Kind.ENUM -> Target.Schema(".${element.fqn}")
+            ReferenceElement.Kind.FIELD, ReferenceElement.Kind.ENUM_VALUE -> Target.Schema(".${element.parent!!.fqn}")
+            ReferenceElement.Kind.SERVICE -> Target.Tag(element.fqn, element.simpleName)
+            ReferenceElement.Kind.RPC -> operationTarget(element)
+        }
+    }
+
+    private fun operationTarget(rpc: ReferenceElement): Target.Operation {
+        val parent = rpc.parent!!
+        val service = parent.descriptor as ServiceDescriptorProtoWrapper
+        val method = rpc.descriptor as MethodDescriptorProtoWrapper
+        val serviceName = parent.simpleName
+        val annotation = method.options?.findExtension(Annotations.method)?.value
+            ?.takeIf { it.hasOperation() }?.operation
+        val serviceTags = service.options?.findExtension(Annotations.service)?.value?.tagsList ?: emptyList()
+        val autoTagName = if (options.autoTagServices) serviceName else null
+        return Target.Operation(
+            serviceFqn = parent.fqn,
+            operationId = operationIdFor(annotation, serviceName, rpc.simpleName),
+            primaryTag = primaryTagFor(autoTagName, serviceTags, annotation),
+            mapped = options.autoMapping || method.options?.findExtension(AnnotationsProto.http)?.value != null,
+        )
+    }
+
+    private fun render(target: Target): ReferenceRendering {
+        val href = when (options.referenceLinkTarget) {
+            ReferenceLinkTarget.NONE -> null
+            ReferenceLinkTarget.REDOC -> redocHref(target)
+            ReferenceLinkTarget.SWAGGER_UI -> swaggerHref(target)
+        }
+        if (href == null) log.debug("reference to {} has no anchor in this document; rendering as inline code", target)
+        return href?.let { ReferenceRendering.Link(it) } ?: ReferenceRendering.Code
+    }
+
+    private fun redocHref(target: Target): String? =
+        when (target) {
+            is Target.Schema -> if (isSchemaEmitted(target.typeName)) "#tag/${schemaKeyResolver.buildPhaseKeyOf(target.typeName)}" else null
+            is Target.Tag -> if (tagEmitted(target)) "#tag/${target.name}" else null
+            is Target.Operation -> if (operationEmitted(target)) "#operation/${target.operationId}" else null
+        }
+
+    private fun swaggerHref(target: Target): String? =
+        when (target) {
+            // Swagger UI has no stable anchor for a component schema.
+            is Target.Schema -> null
+
+            is Target.Tag -> if (tagEmitted(target)) "#/${target.name}" else null
+
+            is Target.Operation -> if (operationEmitted(target)) target.primaryTag?.let { "#/$it/${target.operationId}" } else null
+        }
+
+    private fun tagEmitted(target: Target.Tag): Boolean = options.autoTagServices && isServiceEmitted(target.serviceFqn)
+
+    private fun operationEmitted(target: Target.Operation): Boolean = target.mapped && isServiceEmitted(target.serviceFqn)
+}
+
+/**
+ * The OpenAPI `operationId` for an RPC: the explicit annotation value when set, otherwise a stable
+ * `{ServiceName}_{MethodName}` derivation.  Shared by [PathsBuilder] (which emits it) and
+ * [Descriptions] (which links to it) so the link and the rendered operation always agree.
+ */
+internal fun operationIdFor(
+    annotation: com.engine.protoc.openapi.model.Operation?,
+    serviceName: String,
+    methodName: String,
+): String = annotation?.takeIf { it.hasOperationId() }?.operationId ?: "${serviceName}_$methodName"
+
+/**
+ * The primary OAS tag for an operation — the first of (auto-tag service name, service-level tags,
+ * annotation tags), or `null` when the operation carries no tag.  Mirrors the tag ordering in
+ * [PathsBuilder.buildOperation].
+ */
+internal fun primaryTagFor(
+    autoTagName: String?,
+    serviceTags: List<String>,
+    annotation: com.engine.protoc.openapi.model.Operation?,
+): String? =
+    buildList {
+        autoTagName?.let { add(it) }
+        addAll(serviceTags)
+        annotation?.tagsList?.forEach { add(it) }
+    }.distinct().firstOrNull()
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/PathsBuilder.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/PathsBuilder.kt
index 2422084..8a69a76 100644
--- a/src/main/kotlin/com/engine/protoc/openapi/compile/PathsBuilder.kt
+++ b/src/main/kotlin/com/engine/protoc/openapi/compile/PathsBuilder.kt
@@ -14,6 +14,7 @@ import com.engine.protoc.openapi.model.Schema
 import com.engine.protoc.util.enums.EnumDescriptorProtoWrapper
 import com.engine.protoc.util.enums.EnumValueDescriptorProtoWrapper
 import com.engine.protoc.util.file.FileDescriptorProtoWrapper
+import com.engine.protoc.util.markdown.MarkdownText
 import com.engine.protoc.util.message.DescriptorProtoWrapper
 import com.engine.protoc.util.message.FieldDescriptorProtoWrapper
 import com.engine.protoc.util.service.MethodDescriptorProtoWrapper
@@ -22,34 +23,10 @@ import com.google.api.AnnotationsProto
 import com.google.api.HttpRule
 import com.google.protobuf.DescriptorProtos
 import org.commonmark.node.*
-import org.commonmark.parser.Parser
-import org.commonmark.parser.beta.LinkProcessor
-import org.commonmark.parser.beta.LinkResult
-import org.commonmark.renderer.markdown.MarkdownRenderer
-import org.commonmark.renderer.text.TextContentRenderer
 import org.slf4j.LoggerFactory
 import tools.jackson.databind.node.ArrayNode
 import tools.jackson.databind.node.ObjectNode
-import java.text.BreakIterator
-import java.util.Locale
 
-private val markdownParser: Parser = Parser.builder().build()
-private val markdownRenderer: MarkdownRenderer = MarkdownRenderer.builder().build()
-private val markdownTextRenderer: TextContentRenderer =
-    TextContentRenderer.builder().stripNewlines(true).build()
-
-/**
- * Parser used only for deriving the plain-text `operation.summary`.  Its [LinkProcessor] flattens
- * every link, reference, and image to its visible text, so reference-link syntax such as
- * `[Widget]` or `[Service.Method]` contributes just `Widget` / `Service.Method` to the summary
- * rather than leaving literal square brackets in a field that cannot render Markdown.
- */
-private val summaryParser: Parser =
-    Parser.builder()
-        .linkProcessor { linkInfo, scanner, _ ->
-            LinkResult.replaceWith(Text(linkInfo.text()), scanner.position())
-        }
-        .build()
 private val log = LoggerFactory.getLogger(PathsBuilder::class.java)
 
 /**
@@ -82,8 +59,6 @@ internal class PathsBuilder(
     private val autoMapping: Boolean = false,
     private val inlineRequestSchemas: Boolean = false,
     private val inlineResponseSchemas: Boolean = false,
-    // Non-null when CommonMark reference-link resolution is enabled (referenceLinkTarget != NONE).
-    private val referenceLinkResolver: ReferenceLinkResolver? = null,
     // Resolved `components/parameters` entries (component key → declared parameter `name`),
     // gathered from file- and service-level OpenAPI annotations.  Lets query-parameter
     // auto-derivation honour manual `(engine.protoc.openapi.parameters)` declarations that point
@@ -95,52 +70,7 @@ internal class PathsBuilder(
     // Only populated when autoTagServices is true.
     private val contributingServices = LinkedHashMap<String, String?>()
 
-    // CommonMark parser used for `description` fields.  When a reference-link resolver is
-    // configured, its LinkProcessor is installed so bracketed references rewrite to anchors;
-    // otherwise the plain module-level parser is used.
-    private val descriptionParser: Parser =
-        referenceLinkResolver
-            ?.let { Parser.builder().linkProcessor(it.linkProcessor).build() }
-            ?: markdownParser
-
-    /**
-     * Parses [text] as CommonMark with reference-link resolution bound to [scopeFqn].  The scope
-     * is cleared in a `finally` so a parser exception never leaks a stale scope into the next
-     * comment.  Used by [renderDescription] and the enum-description builder.
-     */
-    private fun parseScoped(
-        text: String,
-        scopeFqn: String,
-    ): Node {
-        referenceLinkResolver?.setCurrentScope(scopeFqn)
-        return try {
-            descriptionParser.parse(text)
-        } finally {
-            referenceLinkResolver?.clearCurrentScope()
-        }
-    }
-
-    /**
-     * Resolves CommonMark reference links in [comment] under [scopeFqn] and returns the result.
-     *
-     * When no resolver is configured (referenceLinkTarget = NONE) the comment is returned
-     * verbatim.  When a resolver is configured but the comment contains no resolvable reference,
-     * the comment is still returned verbatim — only comments whose references actually rewrote to
-     * anchors are re-rendered through the CommonMark renderer, so plain prose keeps its exact
-     * source text.
-     */
-    private fun renderDescription(
-        comment: String,
-        scopeFqn: String,
-    ): String {
-        val resolver = referenceLinkResolver ?: return comment
-        val document = parseScoped(comment, scopeFqn)
-        if (!resolver.consumeTouched()) return comment
-        return markdownRenderer.render(document)
-            .lines()
-            .joinToString("\n") { it.trimEnd() }
-            .trimEnd()
-    }
+    private val descriptions = ctx.descriptions
 
     // Stack of "currently expanding" type names used by [expandInline] for cycle detection.
     // Each frame is the snapshot of expanded types up to the current depth; pushed on entry to
@@ -408,15 +338,18 @@ internal class PathsBuilder(
                 val httpRule = method.httpRule()
                 val binding = resolveBinding(method, httpRule, filePackage, service.name?.value) ?: continue
 
-                val (effectivePath, operationNode) = buildOperation(
-                    method,
-                    binding,
-                    httpRule,
-                    autoTagName,
-                    serviceTags,
-                    serviceName = service.name?.value.orEmpty(),
-                    serviceFqn = fqn(filePackage, service),
-                )
+                // Annotation text on the method (parameters, responses, …) resolves against the method.
+                val (effectivePath, operationNode) = descriptions.withDefaultScope(descriptions.scopeOf(method)) {
+                    buildOperation(
+                        method,
+                        binding,
+                        httpRule,
+                        autoTagName,
+                        serviceTags,
+                        serviceName = service.name?.value.orEmpty(),
+                        serviceFqn = fqn(filePackage, service),
+                    )
+                }
 
                 val slotKey = effectivePath to binding.httpMethod
                 val existingOwner = occupiedSlots[slotKey]
@@ -439,8 +372,8 @@ internal class PathsBuilder(
             // Register this service as a tag source if it produced at least one operation.
             if (autoTagServices && contributed) {
                 val name = service.name?.value ?: continue
-                val description = service.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-                    ?.let { renderDescription(it, fqn(filePackage, service)) }
+                val description = descriptions.comment(service)
+                    ?.let { descriptions.markdown(it, fqn(filePackage, service)) }
                 contributingServices[name] = description
             }
         }
@@ -505,9 +438,10 @@ internal class PathsBuilder(
         val node = ctx.obj()
 
         // ---- Summary (leading comment → annotation override) -------------
-        val comment = method.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-        val summary = annotation?.takeIf { it.hasSummary() }?.summary
-            ?: comment?.firstSentence()?.ifEmpty { null }
+        val methodFqn = descriptions.scopeOf(method).ifEmpty { serviceFqn }
+        val comment = descriptions.comment(method)
+        val summary = annotation?.takeIf { it.hasSummary() }?.summary?.let { descriptions.plain(it, methodFqn) }
+            ?: comment?.let { descriptions.summary(it, methodFqn) }?.ifEmpty { null }
         if (summary != null) node.put("summary", summary)
 
         val description = when {
@@ -515,12 +449,12 @@ internal class PathsBuilder(
             comment != null -> comment
             else -> null
         }
-        if (description != null) node.put("description", renderDescription(description, serviceFqn))
+        if (description != null) node.put("description", descriptions.markdown(description, methodFqn))
 
         // operationId is emitted whenever it is explicitly annotated, or whenever reference-link
         // resolution is enabled — anchors target the operationId, so a stable one must exist on
         // every linkable operation.  The derived value matches [operationIdFor].
-        val operationId = if (annotation?.hasOperationId() == true || referenceLinkResolver != null) {
+        val operationId = if (annotation?.hasOperationId() == true || descriptions.linksOperations) {
             operationIdFor(annotation, serviceName, method.proto.name.orEmpty())
         } else {
             null
@@ -1026,8 +960,9 @@ internal class PathsBuilder(
         val baseHadDescription = base.has("description")
         val annotation = fieldWrapper.options?.findExtension(Annotations.field)?.value
             ?.takeIf { it.hasSchema() }?.schema
+        val fieldFqn = descriptions.scopeOf(fieldWrapper)
         val schema = if (annotation != null && annotation.schemaValueCase == Schema.SchemaValueCase.OBJECT) {
-            with(ctx) { base.deepMerge(annotation.`object`.toJson(ctx)) }
+            descriptions.withDefaultScope(fieldFqn) { with(ctx) { base.deepMerge(annotation.`object`.toJson(ctx)) } }
         } else {
             base
         }
@@ -1036,12 +971,10 @@ internal class PathsBuilder(
         } else {
             null
         }
-        // Annotation-supplied descriptions are verbatim OAS text; the leading proto comment is run
-        // through CommonMark reference-link resolution (no bare-sibling scope — query params
-        // flatten nested fields — but qualified/global references still resolve).
+        // The annotation's description was already resolved when its schema was serialized; the
+        // leading proto comment resolves bare names against the field's siblings and type.
         val description = annotationDescription
-            ?: fieldWrapper.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-                ?.let { renderDescription(it, "") }
+            ?: descriptions.comment(fieldWrapper)?.let { descriptions.markdown(it, fieldFqn) }
         return schema to description
     }
 
@@ -1247,12 +1180,11 @@ internal class PathsBuilder(
      * the literal "Error".
      */
     private fun resolveErrorDescription(er: ErrorResponse): String {
-        if (er.hasDescription() && er.description.isNotEmpty()) return er.description
+        if (er.hasDescription() && er.description.isNotEmpty()) return descriptions.markdown(er.description)
         val typeName = errorResponseTypeName(er)
         if (typeName != null) {
-            val comment = ctx.messageIndex.find(typeName)
-                ?.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-            if (comment != null) return renderDescription(comment, typeName.removePrefix("."))
+            val comment = descriptions.comment(ctx.messageIndex.find(typeName))
+            if (comment != null) return descriptions.markdown(comment, typeName.removePrefix("."))
         }
         return "Error"
     }
@@ -1377,8 +1309,8 @@ internal class PathsBuilder(
         ctx.schemaKeyResolver.titleFor(typeName)?.let { base.put("title", it) }
 
         // ---- Leading comment → description ------------------------------
-        val comment = wrapper.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-        if (comment != null) base.put("description", renderDescription(comment, typeName.removePrefix(".")))
+        val comment = descriptions.comment(wrapper)
+        if (comment != null) base.put("description", descriptions.markdown(comment, typeName.removePrefix(".")))
 
         // ---- Properties from fields -------------------------------------
         val required = mutableListOf<String>()
@@ -1424,7 +1356,7 @@ internal class PathsBuilder(
         return if (annotation != null && annotation.schemaValueCase ==
             Schema.SchemaValueCase.OBJECT
         ) {
-            with(ctx) { base.deepMerge(annotation.`object`.toJson(ctx)) }
+            descriptions.withDefaultScope(typeName.removePrefix(".")) { with(ctx) { base.deepMerge(annotation.`object`.toJson(ctx)) } }
         } else {
             base
         }
@@ -1439,9 +1371,11 @@ internal class PathsBuilder(
         val base = fieldTypeSchema(field)
 
         // ---- Leading comment → description -----------------------------
-        val comment = fieldWrapper.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
+        // Resolved against the field itself, so bare names find its siblings and its type's fields.
+        val fieldFqn = descriptions.scopeOf(fieldWrapper).ifEmpty { scopeFqn }
+        val comment = descriptions.comment(fieldWrapper)
         if (comment != null && !base.has("description")) {
-            base.put("description", renderDescription(comment, scopeFqn))
+            base.put("description", descriptions.markdown(comment, fieldFqn))
         }
 
         // ---- engine.protoc.openapi.field annotation override -----------
@@ -1452,7 +1386,7 @@ internal class PathsBuilder(
         return if (annotation != null && annotation.schemaValueCase ==
             Schema.SchemaValueCase.OBJECT
         ) {
-            with(ctx) { base.deepMerge(annotation.`object`.toJson(ctx)) }
+            descriptions.withDefaultScope(fieldFqn) { with(ctx) { base.deepMerge(annotation.`object`.toJson(ctx)) } }
         } else {
             base
         }
@@ -1618,7 +1552,7 @@ internal class PathsBuilder(
             }
 
             buildEnumDescription(
-                enumComment = enumWrapper.location?.proto?.leadingComments?.trim()?.ifEmpty { null },
+                enumComment = descriptions.comment(enumWrapper),
                 visibleValues = visibleValues,
                 scopeFqn = typeName.removePrefix("."),
             )?.let { node.put("description", it) }
@@ -1639,7 +1573,7 @@ internal class PathsBuilder(
                 ?.findExtension(Annotations.enum_)?.value
                 ?.takeIf { it.hasSchema() }?.schema
             if (annotation != null && annotation.schemaValueCase == Schema.SchemaValueCase.OBJECT) {
-                with(ctx) { node.deepMerge(annotation.`object`.toJson(ctx)) }
+                descriptions.withDefaultScope(typeName.removePrefix(".")) { with(ctx) { node.deepMerge(annotation.`object`.toJson(ctx)) } }
             }
         }
 
@@ -1662,13 +1596,12 @@ internal class PathsBuilder(
             visibleValues.map { valueWrapper ->
                 Pair(
                     formatEnumLabel(valueWrapper.proto.name, valueWrapper.proto.number, ctx.enumValueFormat),
-                    valueWrapper.location?.proto?.leadingComments?.trim()?.ifEmpty { null },
+                    descriptions.comment(valueWrapper),
                 )
             }
         } else {
             visibleValues.mapNotNull { valueWrapper ->
-                val comment = valueWrapper.location?.proto?.leadingComments?.trim()?.ifEmpty { null }
-                    ?: return@mapNotNull null
+                val comment = descriptions.comment(valueWrapper) ?: return@mapNotNull null
                 Pair(
                     formatEnumLabel(valueWrapper.proto.name, valueWrapper.proto.number, ctx.enumValueFormat),
                     comment,
@@ -1678,7 +1611,7 @@ internal class PathsBuilder(
         if (enumComment == null && labeledValues.isEmpty()) return null
 
         val documentNode = if (enumComment != null) {
-            parseScoped(enumComment, scopeFqn) as? Document ?: Document()
+            descriptions.parse(enumComment, scopeFqn) as? Document ?: Document()
         } else {
             Document()
         }
@@ -1686,7 +1619,7 @@ internal class PathsBuilder(
         if (labeledValues.isNotEmpty()) {
             val list = BulletList().apply {
                 for ((name, comment) in labeledValues) {
-                    val commentDoc = comment?.let { parseScoped(it, scopeFqn) as? Document }
+                    val commentDoc = comment?.let { descriptions.parse(it, scopeFqn) as? Document }
                     appendChild(
                         ListItem().apply {
                             val firstBlock = commentDoc?.firstChild
@@ -1718,12 +1651,7 @@ internal class PathsBuilder(
             documentNode.appendChild(list)
         }
 
-        return markdownRenderer
-            .render(documentNode)
-            .lines()
-            .joinToString("\n") { it.trimEnd() }
-            .trimEnd()
-            .ifEmpty { null }
+        return MarkdownText.render(documentNode).ifEmpty { null }
     }
 
     /**
@@ -1782,35 +1710,3 @@ internal fun HttpRule.primaryBinding(): HttpBinding? {
         else -> null
     }
 }
-
-// ---------------------------------------------------------------------------
-// String helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Derives a plain-text summary sentence from a (possibly CommonMark) comment.
- *
- * `operation.summary` is a plain-text field — it does not support CommonMark — so any inline
- * markup in the comment must be stripped rather than passed through. We render the comment's
- * first paragraph to plain text (turning `[label](url)` into `label`, dropping emphasis and code
- * spans), then return its first sentence. A comment that opens with a non-paragraph block (list,
- * heading, fenced code) falls back to the whole rendered document.
- *
- * Sentence boundaries come from [BreakIterator], which is locale-aware and far more reliable than
- * a bare `.`/`!`/`?` scan — it does not split on `e.g.`, decimals (`v1.2`), or URLs.
- */
-private fun String.firstSentence(): String {
-    val document = summaryParser.parse(this)
-    val firstBlock = document.firstChild
-    val plain = if (firstBlock is Paragraph) {
-        markdownTextRenderer.render(firstBlock)
-    } else {
-        markdownTextRenderer.render(document)
-    }.trim()
-    if (plain.isEmpty()) return ""
-
-    val iterator = BreakIterator.getSentenceInstance(Locale.ROOT)
-    iterator.setText(plain)
-    val end = iterator.next()
-    return if (end == BreakIterator.DONE) plain else plain.substring(0, end).trim()
-}
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/ReferenceLinkResolver.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/ReferenceLinkResolver.kt
deleted file mode 100644
index 31f7ec5..0000000
--- a/src/main/kotlin/com/engine/protoc/openapi/compile/ReferenceLinkResolver.kt
+++ /dev/null
@@ -1,415 +0,0 @@
-package com.engine.protoc.openapi.compile
-
-import com.engine.protoc.openapi.Annotations
-import com.engine.protoc.openapi.ProtocGenOpenAPI.Options.ReferenceLinkTarget
-import com.engine.protoc.util.enums.EnumDescriptorProtoWrapper
-import com.engine.protoc.util.file.FileDescriptorProtoWrapper
-import com.engine.protoc.util.message.DescriptorProtoWrapper
-import com.google.api.AnnotationsProto
-import org.commonmark.node.Code
-import org.commonmark.node.Link
-import org.commonmark.parser.beta.LinkInfo
-import org.commonmark.parser.beta.LinkProcessor
-import org.commonmark.parser.beta.LinkResult
-import org.commonmark.parser.beta.Scanner
-import org.slf4j.LoggerFactory
-
-private val log = LoggerFactory.getLogger(ReferenceLinkResolver::class.java)
-
-/**
- * Resolves CommonMark reference-link syntax (`[Widget]`, `[catalog.v1.Widget]`,
- * `[WidgetService.GetWidget]`) inside proto leading comments to same-document anchors in the
- * generated OpenAPI document.  Both the shortcut form (`[label]`) and the full form
- * (`[display text][label]`) are recognized; in the full form the bracketed label is the lookup
- * key and the display text passes through unchanged.  Escaped brackets (`\[foo\]`) and inline
- * links (`[text](url)`) are left to the core CommonMark processor.
- *
- * Constructed once per output document and hooked into the parser as a [LinkProcessor] (see
- * [linkProcessor]); the per-comment scope (the FQN of the descriptor the comment is attached to)
- * flows in through [setCurrentScope], which the caller sets around each `parser.parse(...)` call.
- *
- * Unlike the Markdown generator's resolver, OpenAPI has only three addressable element kinds, and
- * their anchor formats are renderer-specific (see [ReferenceLinkTarget]):
- *
- *  - **messages / enums → component schemas.**  Only addressable under [ReferenceLinkTarget.REDOC]
- *    (Swagger UI has no schema anchors), and only because the compiler emits a `<SchemaDefinition>`
- *    section per schema whose anchor is `#tag/{key}`.  Fields and enum values have no anchor of
- *    their own, so a reference to one resolves to its containing schema.
- *  - **services → tags.**  Addressable only when `autoTagServices` is enabled (otherwise no
- *    service-named tag is emitted).  `#tag/{name}` (Redoc) or `#/{name}` (Swagger UI).
- *  - **RPCs → operations.**  `#operation/{operationId}` (Redoc) or `#/{primaryTag}/{operationId}`
- *    (Swagger UI — which therefore needs the operation to carry at least one tag).
- *
- * Anchors that a target cannot express (e.g. a schema reference in Swagger UI mode, or an
- * operation with no tag) are simply never indexed, so the reference resolves as
- * [Outcome.Unresolved], the brackets are stripped and the label is emitted as an inline code span
- * (e.g. `[Property]` → `` `Property` ``) with a warning, rather than leaking a raw `[label]` that a
- * docs UI would render literally.  Schema anchors are
- * computed from [schemaKeyResolver]'s build-phase key, which is stable for the whole run; the
- * `SIMPLIFIED_PACKAGE` strategy normalizes them to their final form in a post-build pass.
- */
-internal class ReferenceLinkResolver(
-    files: List<FileDescriptorProtoWrapper>,
-    private val target: ReferenceLinkTarget,
-    autoTagServices: Boolean,
-    autoMapping: Boolean,
-    private val schemaKeyResolver: SchemaKeyResolver,
-) {
-    /** Global qualified-name index — every dotted form of every linkable element. */
-    private val qualified = AmbiguityAwareMap("qualified")
-
-    /** Global short-name index for schemas (messages, enums) and services (tags). */
-    private val globalShort = AmbiguityAwareMap("global short name")
-
-    /** scopeFqn (message) → `fieldName → containing-schema href`. */
-    private val fieldsByMessage = mutableMapOf<String, MutableMap<String, String>>()
-
-    /** scopeFqn (enum) → `valueName → containing-schema href`. */
-    private val valuesByEnum = mutableMapOf<String, MutableMap<String, String>>()
-
-    /** scopeFqn (service) → `methodName → operation href`. */
-    private val rpcsByService = mutableMapOf<String, MutableMap<String, String>>()
-
-    /**
-     * The descriptor FQN of the comment currently being parsed, set by the caller via
-     * [setCurrentScope] / [clearCurrentScope] around each `parser.parse(...)` invocation.  Empty
-     * string means "no scope", which disables bare sibling lookups but still allows qualified and
-     * global short-name resolution.
-     */
-    private var currentScope: String = ""
-
-    /**
-     * Whether the most recent parse actually rewrote at least one reference link.  Callers use
-     * this to leave comments that contain no resolvable references byte-for-byte unchanged, rather
-     * than round-tripping every description through the CommonMark renderer.  Reset by
-     * [setCurrentScope] and read via [consumeTouched].
-     */
-    private var touched: Boolean = false
-
-    init {
-        if (target != ReferenceLinkTarget.NONE) index(files, autoTagServices, autoMapping)
-    }
-
-    // -------------------------------------------------------------------------
-    // Anchor formats (renderer-specific)
-    // -------------------------------------------------------------------------
-
-    /** Anchor for a component schema, or `null` when the target cannot address schemas. */
-    private fun schemaHref(key: String): String? =
-        when (target) {
-            ReferenceLinkTarget.REDOC -> "#tag/$key"
-            ReferenceLinkTarget.SWAGGER_UI -> null
-            ReferenceLinkTarget.NONE -> null
-        }
-
-    /** Anchor for a service tag. */
-    private fun tagHref(name: String): String? =
-        when (target) {
-            ReferenceLinkTarget.REDOC -> "#tag/$name"
-            ReferenceLinkTarget.SWAGGER_UI -> "#/$name"
-            ReferenceLinkTarget.NONE -> null
-        }
-
-    /** Anchor for an operation, or `null` when Swagger UI mode lacks a tag to nest under. */
-    private fun operationHref(
-        operationId: String,
-        primaryTag: String?,
-    ): String? =
-        when (target) {
-            ReferenceLinkTarget.REDOC -> "#operation/$operationId"
-            ReferenceLinkTarget.SWAGGER_UI -> primaryTag?.let { "#/$it/$operationId" }
-            ReferenceLinkTarget.NONE -> null
-        }
-
-    // -------------------------------------------------------------------------
-    // Indexing
-    // -------------------------------------------------------------------------
-
-    private fun index(
-        files: List<FileDescriptorProtoWrapper>,
-        autoTagServices: Boolean,
-        autoMapping: Boolean,
-    ) {
-        for (file in files) {
-            val pkg = file.`package`?.value.orEmpty()
-            val pkgPrefix = if (pkg.isEmpty()) "" else "$pkg."
-            for (m in file.messageTypes) indexMessage(m, pkgPrefix, "")
-            for (e in file.enumTypes) indexEnum(e, pkgPrefix, "")
-            for (service in file.services) {
-                indexService(service, pkgPrefix, autoTagServices, autoMapping)
-            }
-        }
-    }
-
-    private fun indexMessage(
-        msg: DescriptorProtoWrapper,
-        pkgPrefix: String,
-        ancestorPrefix: String,
-    ) {
-        if (msg.options?.mapEntry?.value == true) return
-        val short = msg.name?.value ?: return
-        val dotted = if (ancestorPrefix.isEmpty()) short else "$ancestorPrefix.$short"
-        val fqn = "$pkgPrefix$dotted"
-        val href = schemaHref(schemaKeyResolver.buildPhaseKeyOf(".$fqn"))
-
-        if (href != null) {
-            globalShort.put(short, href, "message $fqn")
-            qualified.put(dotted, href, "message $fqn")
-            qualified.put(fqn, href, "message $fqn")
-
-            // Fields and nested members have no anchor of their own; a reference to one points at
-            // the containing schema.
-            val fieldMap = fieldsByMessage.getOrPut(fqn) { mutableMapOf() }
-            for (field in msg.fields) {
-                val fname = field.name?.value ?: continue
-                fieldMap[fname] = href
-                qualified.put("$short.$fname", href, "field $fqn.$fname")
-                if (ancestorPrefix.isNotEmpty()) qualified.put("$dotted.$fname", href, "field $fqn.$fname")
-                qualified.put("$fqn.$fname", href, "field $fqn.$fname")
-            }
-        }
-
-        for (n in msg.nestedTypes) indexMessage(n, pkgPrefix, dotted)
-        for (e in msg.enumTypes) indexEnum(e, pkgPrefix, dotted)
-    }
-
-    private fun indexEnum(
-        enum: EnumDescriptorProtoWrapper,
-        pkgPrefix: String,
-        ancestorPrefix: String,
-    ) {
-        val short = enum.name?.value ?: return
-        val dotted = if (ancestorPrefix.isEmpty()) short else "$ancestorPrefix.$short"
-        val fqn = "$pkgPrefix$dotted"
-        val href = schemaHref(schemaKeyResolver.buildPhaseKeyOf(".$fqn")) ?: return
-
-        globalShort.put(short, href, "enum $fqn")
-        qualified.put(dotted, href, "enum $fqn")
-        qualified.put(fqn, href, "enum $fqn")
-
-        val valueMap = valuesByEnum.getOrPut(fqn) { mutableMapOf() }
-        for (v in enum.values) {
-            val vname = v.name?.value ?: continue
-            valueMap[vname] = href
-            qualified.put("$short.$vname", href, "enum value $fqn.$vname")
-            if (ancestorPrefix.isNotEmpty()) qualified.put("$dotted.$vname", href, "enum value $fqn.$vname")
-            qualified.put("$fqn.$vname", href, "enum value $fqn.$vname")
-        }
-    }
-
-    private fun indexService(
-        service: com.engine.protoc.util.service.ServiceDescriptorProtoWrapper,
-        pkgPrefix: String,
-        autoTagServices: Boolean,
-        autoMapping: Boolean,
-    ) {
-        val sname = service.name?.value ?: return
-        val sFqn = "$pkgPrefix$sname"
-        val serviceTags = service.options?.findExtension(Annotations.service)?.value?.tagsList ?: emptyList()
-        val autoTagName = if (autoTagServices) sname else null
-
-        tagHrefForService(autoTagName)?.let { href ->
-            globalShort.put(sname, href, "service $sFqn")
-            qualified.put(sname, href, "service $sFqn")
-            qualified.put(sFqn, href, "service $sFqn")
-        }
-
-        val rpcMap = rpcsByService.getOrPut(sFqn) { mutableMapOf() }
-        for (method in service.methods) {
-            val mname = method.proto.name ?: continue
-            val hasHttp = method.options?.findExtension(AnnotationsProto.http)?.value != null
-            // Only methods that become operations are linkable.
-            if (!hasHttp && !autoMapping) continue
-            val annotation = method.options?.findExtension(Annotations.method)?.value
-                ?.takeIf { it.hasOperation() }?.operation
-            val operationId = operationIdFor(annotation, sname, mname)
-            val primaryTag = primaryTagFor(autoTagName, serviceTags, annotation)
-            val href = operationHref(operationId, primaryTag) ?: continue
-            rpcMap[mname] = href
-            qualified.put("$sname.$mname", href, "rpc $sFqn.$mname")
-            qualified.put("$sFqn.$mname", href, "rpc $sFqn.$mname")
-        }
-    }
-
-    private fun tagHrefForService(autoTagName: String?): String? = autoTagName?.let { tagHref(it) }
-
-    // -------------------------------------------------------------------------
-    // Resolution
-    // -------------------------------------------------------------------------
-
-    private fun resolve(
-        label: String,
-        scopeFqn: String,
-    ): Outcome {
-        if (label.isEmpty()) return Outcome.Unresolved
-        if ('.' in label) return qualified.lookup(label)
-
-        var ambiguous: Outcome.Ambiguous? = null
-        bareScopeOutcome(label, scopeFqn)?.let {
-            if (it is Outcome.Resolved) return it
-            if (it is Outcome.Ambiguous && ambiguous == null) ambiguous = it
-        }
-        globalShort.lookup(label).let {
-            if (it is Outcome.Resolved) return it
-            if (it is Outcome.Ambiguous && ambiguous == null) ambiguous = it
-        }
-        return ambiguous ?: Outcome.Unresolved
-    }
-
-    /** Bare sibling lookup against the comment's own scope (message fields, enum values, RPCs). */
-    private fun bareScopeOutcome(
-        label: String,
-        scopeFqn: String,
-    ): Outcome? {
-        if (scopeFqn.isEmpty()) return null
-        val href = fieldsByMessage[scopeFqn]?.get(label)
-            ?: valuesByEnum[scopeFqn]?.get(label)
-            ?: rpcsByService[scopeFqn]?.get(label)
-            ?: return null
-        return Outcome.Resolved(href)
-    }
-
-    /** Bind the FQN of the comment about to be parsed.  Pair with [clearCurrentScope]. */
-    fun setCurrentScope(scopeFqn: String) {
-        currentScope = scopeFqn
-        touched = false
-    }
-
-    /** Reset to no scope.  See [setCurrentScope]. */
-    fun clearCurrentScope() {
-        currentScope = ""
-    }
-
-    /** `true` when the parse since the last [setCurrentScope] rewrote at least one reference link. */
-    fun consumeTouched(): Boolean = touched
-
-    // -------------------------------------------------------------------------
-    // LinkProcessor hook
-    // -------------------------------------------------------------------------
-
-    val linkProcessor: LinkProcessor =
-        LinkProcessor { linkInfo, scanner, _ -> processLink(linkInfo, scanner) }
-
-    private fun processLink(
-        linkInfo: LinkInfo,
-        scanner: Scanner,
-    ): LinkResult? {
-        // Inline links (`[text](url)`) and images carry a destination/marker — leave to core.
-        if (linkInfo.destination() != null) return LinkResult.none()
-        if (linkInfo.marker() != null) return LinkResult.none()
-        val rawLabel = linkInfo.label()
-        val text = linkInfo.text()
-        val key = if (rawLabel.isNullOrEmpty()) text else rawLabel
-        if (key.isEmpty()) return LinkResult.none()
-
-        return when (val outcome = resolve(key, currentScope)) {
-            is Outcome.Resolved -> {
-                touched = true
-                LinkResult.wrapTextIn(Link(outcome.href, null), scanner.position())
-            }
-
-            is Outcome.Ambiguous -> {
-                warn(key, "ambiguous; candidates: ${outcome.candidates.joinToString("; ")}")
-                touched = true
-                LinkResult.wrapTextIn(Link(outcome.href, null), scanner.position())
-            }
-
-            Outcome.Unresolved -> {
-                warn(key, "no matching schema, tag, or operation anchor in compile scope")
-                // Strip the brackets rather than leaving a raw `[label]` (which renders as literal
-                // text in the docs UI).  The label is emitted as an inline code span so it still
-                // reads as a referenced symbol — e.g. an unaddressable schema like `[Property]`
-                // becomes `` `Property` `` instead of `[Property]`.
-                touched = true
-                LinkResult.replaceWith(Code(text), scanner.position())
-            }
-        }
-    }
-
-    private fun warn(
-        label: String,
-        reason: String,
-    ) {
-        log.warn(
-            "reference-link [{}] in {} :: {} — {}; rendering as inline code",
-            label,
-            target,
-            currentScope.ifEmpty { "(no scope)" },
-            reason,
-        )
-    }
-
-    // -------------------------------------------------------------------------
-    // Helpers
-    // -------------------------------------------------------------------------
-
-    /** Per-map `key → href` index that records every owner so collisions surface as ambiguous. */
-    private inner class AmbiguityAwareMap(private val mapLabel: String) {
-        private val hrefByKey = mutableMapOf<String, String>()
-        private val candidatesByKey = mutableMapOf<String, MutableList<Pair<String, String>>>()
-
-        fun put(
-            key: String,
-            href: String,
-            owner: String,
-        ) {
-            val candidates = candidatesByKey.getOrPut(key) { mutableListOf() }
-            if (candidates.any { it.first == owner && it.second == href }) return
-            candidates += owner to href
-            val prior = hrefByKey[key]
-            if (prior != null && prior != href && log.isTraceEnabled) {
-                log.trace(
-                    "reference-link key '{}' in {} is ambiguous — '{}' collides with prior '{}'; keeping latest",
-                    key,
-                    mapLabel,
-                    owner,
-                    prior,
-                )
-            }
-            hrefByKey[key] = href
-        }
-
-        fun lookup(key: String): Outcome {
-            val href = hrefByKey[key] ?: return Outcome.Unresolved
-            val distinct = candidatesByKey[key].orEmpty().map { it.second }.distinct()
-            return if (distinct.size <= 1) {
-                Outcome.Resolved(href)
-            } else {
-                Outcome.Ambiguous(href, candidatesByKey[key].orEmpty().map { "${it.first} → ${it.second}" })
-            }
-        }
-    }
-
-    private sealed class Outcome {
-        data class Resolved(val href: String) : Outcome()
-        data class Ambiguous(val href: String, val candidates: List<String>) : Outcome()
-        object Unresolved : Outcome()
-    }
-}
-
-/**
- * The OpenAPI `operationId` for an RPC: the explicit annotation value when set, otherwise a stable
- * `{ServiceName}_{MethodName}` derivation.  Shared by [PathsBuilder] (which emits it) and
- * [ReferenceLinkResolver] (which links to it) so the link and the rendered operation always agree.
- */
-internal fun operationIdFor(
-    annotation: com.engine.protoc.openapi.model.Operation?,
-    serviceName: String,
-    methodName: String,
-): String = annotation?.takeIf { it.hasOperationId() }?.operationId ?: "${serviceName}_$methodName"
-
-/**
- * The primary OAS tag for an operation — the first of (auto-tag service name, service-level tags,
- * annotation tags), or `null` when the operation carries no tag.  Mirrors the tag ordering in
- * [PathsBuilder.buildOperation].
- */
-internal fun primaryTagFor(
-    autoTagName: String?,
-    serviceTags: List<String>,
-    annotation: com.engine.protoc.openapi.model.Operation?,
-): String? =
-    buildList {
-        autoTagName?.let { add(it) }
-        addAll(serviceTags)
-        annotation?.tagsList?.forEach { add(it) }
-    }.distinct().firstOrNull()
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/json/JsonContext.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/json/JsonContext.kt
index 459bf2e..d0c755f 100644
--- a/src/main/kotlin/com/engine/protoc/openapi/compile/json/JsonContext.kt
+++ b/src/main/kotlin/com/engine/protoc/openapi/compile/json/JsonContext.kt
@@ -1,6 +1,7 @@
 package com.engine.protoc.openapi.compile.json
 
 import com.engine.protoc.openapi.ProtocGenOpenAPI
+import com.engine.protoc.openapi.compile.Descriptions
 import com.engine.protoc.openapi.compile.EnumIndex
 import com.engine.protoc.openapi.compile.MessageIndex
 import com.engine.protoc.openapi.compile.RpcIndex
@@ -54,6 +55,11 @@ internal class JsonContext(
      * Mirrors Envoy's `stream_sse_style_delimited` PrintOption.
      */
     val streamSseStyleDelimited: Boolean = false,
+    /**
+     * Produces every emitted `description`, `summary`, and `title` string, resolving reference
+     * links and scrubbing Markdown from plain-text fields.
+     */
+    val descriptions: Descriptions,
 ) {
     fun obj(): ObjectNode = mapper.createObjectNode()
 
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/json/OpenApiSerializer.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/json/OpenApiSerializer.kt
index d0db9a4..e97c61d 100644
--- a/src/main/kotlin/com/engine/protoc/openapi/compile/json/OpenApiSerializer.kt
+++ b/src/main/kotlin/com/engine/protoc/openapi/compile/json/OpenApiSerializer.kt
@@ -133,9 +133,9 @@ internal fun Map<String, Value>.putExtensionsInto(
 
 internal fun Info.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
-    if (title.isNotEmpty()) node.put("title", title)
-    if (hasSummary()) node.put("summary", summary)
-    if (hasDescription()) node.put("description", description)
+    if (title.isNotEmpty()) node.put("title", ctx.descriptions.plain(title))
+    if (hasSummary()) node.put("summary", ctx.descriptions.plain(summary))
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasTermsOfService()) node.put("termsOfService", termsOfService)
     if (hasContact()) node.set("contact", contact.toJson(ctx))
     if (hasLicense()) node.set("license", license.toJson(ctx))
@@ -167,7 +167,7 @@ internal fun License.toJson(ctx: JsonContext): ObjectNode {
 internal fun Server.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
     node.put("url", url)
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (variablesMap.isNotEmpty()) {
         val varNode = ctx.obj()
         for ((k, v) in variablesMap) varNode.set(k, v.toJson(ctx))
@@ -184,7 +184,7 @@ internal fun ServerVariable.toJson(ctx: JsonContext): ObjectNode {
         node.set("enum", arr)
     }
     node.put("default", default)
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     return node
 }
 
@@ -195,7 +195,7 @@ internal fun ServerVariable.toJson(ctx: JsonContext): ObjectNode {
 internal fun Tag.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
     node.put("name", name)
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasExternalDocs()) node.set("externalDocs", externalDocs.toJson(ctx))
     extensionsMap.putExtensionsInto(node, ctx)
     return node
@@ -221,8 +221,8 @@ internal fun PathItem.toJson(ctx: JsonContext): ObjectNode {
         PathItem.RefTypeCase.PROTO_RPC_REF -> node.put("\$ref", ctx.resolveProtoRpcRef(protoRpcRef, includeMethod = false))
         else -> {}
     }
-    if (hasSummary()) node.put("summary", summary)
-    if (hasDescription()) node.put("description", description)
+    if (hasSummary()) node.put("summary", ctx.descriptions.plain(summary))
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasGet()) node.set("get", get.toJson(ctx))
     if (hasPut()) node.set("put", put.toJson(ctx))
     if (hasPost()) node.set("post", post.toJson(ctx))
@@ -256,8 +256,8 @@ internal fun Operation.toJson(ctx: JsonContext): ObjectNode {
         for (t in tagsList) arr.add(t)
         node.set("tags", arr)
     }
-    if (hasSummary()) node.put("summary", summary)
-    if (hasDescription()) node.put("description", description)
+    if (hasSummary()) node.put("summary", ctx.descriptions.plain(summary))
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasExternalDocs()) node.set("externalDocs", externalDocs.toJson(ctx))
     if (hasOperationId()) node.put("operationId", operationId)
     if (parametersList.isNotEmpty()) {
@@ -305,7 +305,7 @@ internal fun Parameter.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
     node.put("name", name)
     node.put("in", `in`)
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasRequired()) node.put("required", required)
     if (hasDeprecated()) node.put("deprecated", deprecated)
     if (hasAllowEmptyValue()) node.put("allowEmptyValue", allowEmptyValue)
@@ -356,7 +356,7 @@ internal fun RequestBodyOrReference.toJson(ctx: JsonContext): ObjectNode =
 
 internal fun RequestBody.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (contentMap.isNotEmpty()) {
         val contentNode = ctx.obj()
         for ((k, v) in contentMap) contentNode.set(k, v.toJson(ctx))
@@ -416,7 +416,7 @@ internal fun ResponseOrReference.toJson(ctx: JsonContext): ObjectNode =
 
 internal fun ResponseObject.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
-    node.put("description", description)
+    node.put("description", ctx.descriptions.markdown(description))
     if (headersMap.isNotEmpty()) {
         val headersNode = ctx.obj()
         for ((k, v) in headersMap) headersNode.set(k, v.toJson(ctx))
@@ -468,7 +468,7 @@ internal fun Link.toJson(ctx: JsonContext): ObjectNode {
         node.set("parameters", paramsNode)
     }
     if (hasRequestBody()) node.set("requestBody", requestBody.toJson(ctx))
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasServer()) node.set("server", server.toJson(ctx))
     return node
 }
@@ -504,7 +504,7 @@ internal fun HeaderOrReference.toJson(ctx: JsonContext): ObjectNode =
 
 internal fun Header.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasRequired()) node.put("required", required)
     if (hasDeprecated()) node.put("deprecated", deprecated)
     // A Header uses either schema-based or content-based serialization, never both.
@@ -559,8 +559,8 @@ internal fun ExampleOrReference.toJson(ctx: JsonContext): ObjectNode =
 
 internal fun Example.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
-    if (hasSummary()) node.put("summary", summary)
-    if (hasDescription()) node.put("description", description)
+    if (hasSummary()) node.put("summary", ctx.descriptions.plain(summary))
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     when (typeCase) {
         Example.TypeCase.VALUE -> node.set("value", value.toJson(ctx))
         Example.TypeCase.EXTERNAL_VALUE -> node.put("externalValue", externalValue)
@@ -655,6 +655,7 @@ internal fun SecurityScheme.toJson(ctx: JsonContext): ObjectNode {
         SecurityScheme.TypeCase.OPEN_ID_CONNECT -> openIdConnect.toJson(ctx)
         else -> ctx.obj()
     }
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     extensionsMap.putExtensionsInto(node, ctx)
     return node
 }
@@ -700,7 +701,7 @@ internal fun OAuthFlow.toJson(ctx: JsonContext): ObjectNode {
     if (hasRefreshUrl()) node.put("refreshUrl", refreshUrl)
     if (scopesMap.isNotEmpty()) {
         val scopeNode = ctx.obj()
-        for ((k, v) in scopesMap) scopeNode.put(k, v)
+        for ((k, v) in scopesMap) scopeNode.put(k, ctx.descriptions.plain(v))
         node.set("scopes", scopeNode)
     }
     return node
@@ -724,7 +725,7 @@ internal fun Reference.toJson(ctx: JsonContext): ObjectNode {
         Reference.RefTypeCase.PROTO_RPC_REF -> node.put("\$ref", ctx.resolveProtoRpcRef(protoRpcRef, includeMethod = false))
         else -> {}
     }
-    if (hasSummary()) node.put("summary", summary)
-    if (hasDescription()) node.put("description", description)
+    if (hasSummary()) node.put("summary", ctx.descriptions.plain(summary))
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     return node
 }
diff --git a/src/main/kotlin/com/engine/protoc/openapi/compile/json/SchemaSerializer.kt b/src/main/kotlin/com/engine/protoc/openapi/compile/json/SchemaSerializer.kt
index 4cfcfd2..b2f8871 100644
--- a/src/main/kotlin/com/engine/protoc/openapi/compile/json/SchemaSerializer.kt
+++ b/src/main/kotlin/com/engine/protoc/openapi/compile/json/SchemaSerializer.kt
@@ -48,8 +48,8 @@ internal fun SchemaObject.toJson(ctx: JsonContext): ObjectNode {
     }
 
     // ---- Metadata --------------------------------------------------------
-    if (hasTitle()) node.put("title", title)
-    if (hasDescription()) node.put("description", description)
+    if (hasTitle()) node.put("title", ctx.descriptions.plain(title))
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     if (hasDeprecated()) node.put("deprecated", deprecated)
     if (hasReadOnly()) node.put("readOnly", readOnly)
     if (hasWriteOnly()) node.put("writeOnly", writeOnly)
@@ -202,7 +202,7 @@ internal fun XML.toJson(ctx: JsonContext): ObjectNode {
 
 internal fun ExternalDocumentation.toJson(ctx: JsonContext): ObjectNode {
     val node = ctx.obj()
-    if (hasDescription()) node.put("description", description)
+    if (hasDescription()) node.put("description", ctx.descriptions.markdown(description))
     node.put("url", url)
     return node
 }