@redpanda-data/docs-extensions-and-macros 5.54.0 → 5.55.0

package/mcp/USER_GUIDE.adoc

@@ -200,24 +200,6 @@ The MCP server provides *writer-friendly tools* designed for natural language in
 * Requires knowledge of doc-tools CLI syntax
 * Only works in repos that have doc-tools installed
 
-=== Contextual guides (prompts)
-
-*property-docs-guide*:: Comprehensive guide for updating Redpanda property documentation
-+
-* Explains the auto-generation system and override workflow
-* Provides rules for property descriptions (no cloud conditionals, no enterprise includes)
-* Lists common scenarios and validation steps
-* Claude automatically retrieves this when working with property documentation
-* Ensures correct workflow: update property-overrides.json, not generated .adoc files
-
-*rpcn-connector-docs-guide*:: Comprehensive guide for updating Redpanda Connect connector reference documentation
-+
-* Explains the override system with `$ref` syntax for DRY (Don't Repeat Yourself) principles
-* Describes repository structure and how autogenerated content works with overrides
-* Provides workflow for improving connector documentation
-* Claude automatically retrieves this when working with connector documentation
-* Ensures correct workflow: update docs-data/overrides.json, use $ref for deduplication
-
 === Background job management
 
 Long-running documentation generation tasks support background execution with progress updates:
@@ -265,130 +247,38 @@ Background jobs send real-time progress notifications via MCP protocol, so Claud
 
 All commands have a 10-minute timeout (increased from 5 minutes) to handle large documentation generation tasks.
 
-== Available prompts
-
-The MCP server provides *AI consistency prompts* that help Claude follow your team's documentation standards automatically. These prompts are pre-configured instructions that guide Claude's responses for common documentation tasks.
-
-=== Documentation review prompts
-
-*review-for-style*:: Review documentation content for style guide compliance
-+
-* Checks: Style guide compliance, terminology consistency, voice/tone, AsciiDoc formatting
-* Input: Content to review (can be file path or raw text)
-* Output: Detailed feedback with critical issues, suggestions, and actionable recommendations
-* Use when: Reviewing any documentation before publishing
-
-*check-terminology*:: Validate terminology usage against approved team terminology
-+
-* Checks: Incorrect terms, deprecated terms (whitelist/blacklist, master/slave), inconsistent usage
-* Input: Content to check
-* Output: Critical issues with corrections, inconsistencies found, missing glossary links
-* Use when: Ensuring consistent terminology across documentation
-
-*improve-clarity*:: Refactor existing documentation for clarity and readability
-+
-* Applies: Style guide principles, simplifies complex explanations, improves structure
-* Input: Content to improve
-* Output: Refactored content with explanations of changes made
-* Use when: Content is technically correct but difficult to understand
-
-=== Content creation prompts
-
-*write-new-guide*:: Generate a new tutorial or guide following team standards
-+
-* Applies: Team templates, approved terminology, voice/tone guidelines, AsciiDoc formatting
-* Input: Topic (what to write about), optional audience (beginners, experienced devs, operators)
-* Output: Complete guide following team standards
-* Use when: Starting a new tutorial, how-to, or getting started guide
-
-=== Workflow guide prompts
-
-*property-docs-guide*:: Comprehensive guide for updating Redpanda property documentation
-+
-* Explains: Auto-generation system, override workflow, validation steps
-* Rules: Never edit generated `.adoc` files, always update `property-overrides.json`
-* Use when: Claude is helping with property documentation
-* Claude automatically retrieves this prompt when working with properties
-
-*rpcn-connector-docs-guide*:: Guide for updating Redpanda Connect connector documentation
-+
-* Explains: Override system with `$ref` syntax for DRY principles, repository structure
-* Rules: Update `docs-data/overrides.json`, use `$ref` for deduplication
-* Use when: Claude is helping with connector documentation
-* Claude automatically retrieves this prompt when working with connectors
-
-=== How to use prompts
+== Guidance from docs-team-standards
 
-Prompts work through natural conversation with Claude Code:
+This server provides tools and one resource. It has no MCP prompts. Writing, review, and workflow guidance lives in the https://github.com/redpanda-data/docs-team-standards[docs-team-standards^] Claude Code plugin:
 
-*Explicit prompt usage:*
+[cols="1,2"]
+|===
+|Task |docs-team-standards
 
-----
-You: "Use the review-for-style prompt with this content: [paste content]"
-Claude: *retrieves and applies the review-for-style prompt*
-        *provides structured feedback following the prompt instructions*
-----
-
-*Implicit prompt usage:*
-
-----
-You: "Review this tutorial for our style guide"
-Claude: *automatically uses review-for-style prompt*
-        *provides feedback based on your team standards*
-----
-
-*Listing available prompts:*
-
-----
-You: "List available prompts"
-Claude: *shows all prompts with descriptions*
-----
-
-You can also preview prompts using the CLI:
+|Review content for style, terminology, structure, and clarity
+|The `review` skill, the `/review` command, or the `content-reviewer` agent
 
-[,bash]
-----
-# Preview a review prompt
-npx doc-tools preview-prompt review-for-style --content "Test content"
-
-# Preview a write prompt
-npx doc-tools preview-prompt write-new-guide --topic "Deploy cluster"
+|Write a new page or guide
+|The `page-templates` skill and the `/plan` command
 
-# List all prompts with versions
-npx doc-tools mcp-version
-----
+|Update property documentation
+|The `property-overrides` skill
+|===
 
 == Available resources
 
-Resources are reference materials that Claude can read to understand your team's standards.
-
-=== Style guide
-
-*redpanda://style-guide*:: Redpanda Documentation Style Guide (v1.0.0)
+*redpanda://personas*:: Target audience personas for the current repository
 +
-* Complete style guide based on Google Developer Documentation Style Guide
-* Includes: Redpanda-specific guidelines, voice and tone, AsciiDoc formatting rules
-* Contains: Terminology quick reference, formatting examples, common patterns
-* Claude automatically references this when reviewing or writing documentation
+* Loaded from `docs-data/personas.yaml` in your current working directory
+* Defines reader types, goals, pain points, and content preferences
 
-=== How to use resources
-
-Resources are automatically loaded by prompts, but you can also reference them explicitly:
-
-*Explicit reference:*
+To read it, ask Claude directly:
 
 ----
-You: "Read the redpanda://style-guide resource and tell me the rules for code blocks"
-Claude: *reads the style guide resource*
-        *explains the code block formatting rules*
+You: "Read the redpanda://personas resource and summarize the target readers"
 ----
 
-*Listing available resources:*
-
-----
-You: "List available resources"
-Claude: *shows all resources with descriptions and versions*
-----
+The style guide lives in docs-team-standards, not in this server.
 
 === Design philosophy
 
@@ -972,12 +862,12 @@ Suggestion: Check that the version exists in the Redpanda repository. You can fi
 https://github.com/redpanda-data/streaming-enterprise/releases
 ----
 
-=== Example 7: Property documentation updates (with prompt)
+=== Example 7: Property documentation updates
 
 ----
 You: Improve the description for cleanup.policy property to explain what each value does
 
-Claude: *retrieves property-docs-guide prompt*
+Claude: *uses the property-overrides skill from docs-team-standards*
         *reads property-overrides.json*
         *updates the description field with enhanced explanation*
         *uses generate_property_docs MCP tool with generate_partials: true*
@@ -995,7 +885,7 @@ The description now explains:
 - `compact,delete` - Compaction + time-based deletion
 ----
 
-This example shows how the prompt automatically provides context about the property documentation workflow, ensuring Claude follows the correct process (update overrides, not generated files).
+The skill provides the property documentation workflow, so Claude updates the overrides file, not the generated files.
 
 === Example 8: Review documentation for style compliance
 
@@ -1004,7 +894,7 @@ You: Review this tutorial for style guide compliance:
 
 [Content of tutorial pasted here]
 
-Claude: *uses review-for-style prompt*
+Claude: *uses the review skill from docs-team-standards*
         *analyzes content against team style guide*
 
 Style Review for Tutorial
@@ -1042,7 +932,7 @@ Overall: Good structure, clear explanations. Fix critical issues before publishi
 ----
 You: Check the terminology in this doc for any deprecated or incorrect terms
 
-Claude: *uses check-terminology prompt*
+Claude: *uses the review skill from docs-team-standards*
 
 Terminology Review
 ==========================================
@@ -1070,7 +960,7 @@ Summary:
 ----
 You: Write a getting started guide for deploying a 3-node Redpanda cluster
 
-Claude: *uses write-new-guide prompt*
+Claude: *uses the page-templates skill from docs-team-standards*
         *applies team templates and standards*
 
 = Deploy a Three-Node Redpanda Cluster
@@ -1103,7 +993,7 @@ You: This explanation of compaction is too complex. Can you simplify it?
 
 [Paste complex explanation]
 
-Claude: *uses improve-clarity prompt*
+Claude: *uses the review skill from docs-team-standards*
 
 Here's a clearer version:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.54.0",
+  "version": "5.55.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -94,7 +94,9 @@
     "./extensions/property-page-index": "./extensions/property-page-index.js",
     "./extensions/render-property-descriptions": "./extensions/render-property-descriptions.js",
     "./extensions/kapa-source-groups": "./extensions/kapa-source-groups.js",
-    "./docs-data/kapa-source-groups.json": "./docs-data/kapa-source-groups.json"
+    "./docs-data/kapa-source-groups.json": "./docs-data/kapa-source-groups.json",
+    "./macros/iceberg-explorer": "./macros/iceberg-explorer.js",
+    "./macros/iceberg-explorer.js": "./macros/iceberg-explorer.js"
   },
   "files": [
     "extensions",

package/tools/doc-impact-recording/index.js

@@ -0,0 +1,190 @@
+'use strict'
+
+/**
+ * Turn a Claude Code transcript into a doc-impact MCP recording.
+ *
+ * The doc-strings review asks the docs MCP server (docs.redpanda.com/mcp)
+ * whether published pages already cover a changed string. The doc-impact
+ * eval replays those answers per item, so an eval run sees the docs as they
+ * were when the review ran, not as they are today. A recording made later
+ * would already contain the writer's fix for the PR, and the pass would
+ * then correctly say "already documented" for a PR that needed docs.
+ *
+ * This reads the transcript the review step leaves behind and keeps only
+ * what a replay needs: the tool name, its arguments, and the result content.
+ * Nothing else from the transcript is copied, so the session's tokens,
+ * headers, environment and identity never reach the recording.
+ *
+ * The arguments are the model's own text, though, and the review reads
+ * untrusted PR content. A call whose arguments or result contain something
+ * shaped like a credential is dropped rather than saved, because the
+ * recording is uploaded as an artifact and log masking doesn't cover
+ * artifacts.
+ *
+ * Accepted input:
+ *   - the execution file anthropics/claude-code-action writes: one JSON
+ *     array of SDK messages;
+ *   - `claude -p --output-format stream-json` output: one message per line.
+ * Both carry the same message shapes, so one parser serves both.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const DEFAULT_SERVER = 'redpanda-docs'
+
+// Credential shapes a recording must never carry: GitHub tokens (classic and
+// fine-grained), JWTs (which include GitHub App and OIDC tokens), and AWS
+// access key IDs.
+const SECRET_PATTERNS = [
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/,
+  /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/
+]
+
+/** Whether a value, serialized, contains anything shaped like a credential. */
+function looksSecret (value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value)
+  return SECRET_PATTERNS.some((re) => re.test(text || ''))
+}
+
+/** Messages from a transcript, in order. Lines that are not JSON are skipped. */
+function parseTranscript (text) {
+  const raw = String(text || '')
+  const trimmed = raw.trim()
+  if (trimmed.startsWith('[')) {
+    try {
+      const all = JSON.parse(trimmed)
+      if (Array.isArray(all)) return all.filter((m) => m && typeof m === 'object')
+    } catch {
+      // Not one JSON document; read it line by line below.
+    }
+  }
+  const out = []
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const m = JSON.parse(line)
+      if (m && typeof m === 'object' && !Array.isArray(m)) out.push(m)
+    } catch {
+      // Progress lines and other non-JSON output are not messages.
+    }
+  }
+  return out
+}
+
+/** Tool-result content as an array of MCP content blocks. */
+function contentBlocks (content) {
+  if (content == null) return []
+  if (typeof content === 'string') return [{ type: 'text', text: content }]
+  if (Array.isArray(content)) return content.map((b) => (typeof b === 'string' ? { type: 'text', text: b } : b))
+  return [{ type: 'text', text: JSON.stringify(content) }]
+}
+
+function blocksOf (message) {
+  const content = message && message.message && message.message.content
+  return Array.isArray(content) ? content : []
+}
+
+/**
+ * Every call to one MCP server's tools, paired with its result, in call
+ * order. A call with no result (the run stopped first) is left out: a
+ * replay of it would answer with nothing the server ever said.
+ */
+function extractCalls (messages, { server = DEFAULT_SERVER } = {}) {
+  const prefix = `mcp__${server}__`
+  const calls = []
+  const byId = new Map()
+  for (const m of messages || []) {
+    if (m.type === 'assistant') {
+      for (const b of blocksOf(m)) {
+        if (b && b.type === 'tool_use' && typeof b.name === 'string' && b.name.startsWith(prefix)) {
+          const call = { tool: b.name.slice(prefix.length), arguments: b.input || {}, content: null, is_error: false }
+          calls.push(call)
+          byId.set(b.id, call)
+        }
+      }
+    } else if (m.type === 'user') {
+      for (const b of blocksOf(m)) {
+        if (b && b.type === 'tool_result' && byId.has(b.tool_use_id)) {
+          const call = byId.get(b.tool_use_id)
+          call.content = contentBlocks(b.content)
+          call.is_error = Boolean(b.is_error)
+        }
+      }
+    }
+  }
+  return calls.filter((c) => c.content !== null)
+}
+
+/** Split calls into the ones safe to save and the count dropped as secret-bearing. */
+function dropSecretCalls (calls) {
+  const kept = calls.filter((c) => !looksSecret(c.arguments) && !looksSecret(c.content))
+  return { kept, dropped: calls.length - kept.length }
+}
+
+/** The model the session ran on, from its init message. */
+function sessionModel (messages) {
+  const init = (messages || []).find((m) => m.type === 'system' && m.subtype === 'init')
+  return (init && typeof init.model === 'string' && init.model) || null
+}
+
+/**
+ * A recording in the shape the doc-impact eval replays:
+ * { item, recorded_at, server_url, model, source, calls: [{ tool, arguments, content, is_error }] }
+ */
+function buildRecording (messages, { item = null, recordedAt, serverUrl = null, model = null, server = DEFAULT_SERVER } = {}) {
+  const { kept, dropped } = dropSecretCalls(extractCalls(messages, { server }))
+  const recording = {
+    item,
+    recorded_at: recordedAt || new Date().toISOString(),
+    server_url: serverUrl,
+    model: model || sessionModel(messages),
+    source: 'production',
+    calls: kept
+  }
+  // Not enumerable, so it never reaches the written file.
+  Object.defineProperty(recording, 'droppedSecretCalls', { value: dropped })
+  return recording
+}
+
+/**
+ * CLI entry: read --execution-file, write --output. Writes nothing when the
+ * session made no docs calls it can save, and removes any file an earlier
+ * run left at --output, so the caller can tell "no calls" from "a
+ * recording" by the file's presence. Exits 0 either way; a missing or
+ * unreadable transcript is exit 1.
+ */
+function runCli (options, { log = console.log, error = console.error } = {}) {
+  const file = options.executionFile
+  let text
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch (e) {
+    error(`Cannot read the transcript at ${file}: ${e.message}`)
+    return 1
+  }
+  const messages = parseTranscript(text)
+  const recording = buildRecording(messages, {
+    item: options.item || null,
+    recordedAt: options.recordedAt,
+    serverUrl: options.serverUrl || null,
+    model: options.model || null,
+    server: options.server || DEFAULT_SERVER
+  })
+  if (recording.droppedSecretCalls) {
+    error(`Dropped ${recording.droppedSecretCalls} MCP call(s) whose arguments or result look like a credential.`)
+  }
+  if (!recording.calls.length) {
+    fs.rmSync(options.output, { force: true })
+    log(`No ${options.server || DEFAULT_SERVER} MCP calls to save in ${messages.length} transcript message(s); no recording written.`)
+    return 0
+  }
+  fs.mkdirSync(path.dirname(path.resolve(options.output)), { recursive: true })
+  fs.writeFileSync(options.output, JSON.stringify(recording, null, 2) + '\n')
+  log(`Wrote ${recording.calls.length} ${options.server || DEFAULT_SERVER} MCP call(s) to ${options.output}.`)
+  return 0
+}
+
+module.exports = { parseTranscript, extractCalls, sessionModel, buildRecording, dropSecretCalls, looksSecret, runCli, DEFAULT_SERVER }

package/tools/overrides-audit/README.adoc

@@ -22,7 +22,7 @@ npx doc-tools overrides audit \
   --format human
 
 # Standalone
-node tools/overrides-audit/index.js --overrides <path> --extracted <path> [--surface properties|rpk|connect] [--format json|human] [--output <file>]
+node tools/overrides-audit/index.js --overrides <path> --extracted <path> [--surface properties|rpk] [--format json|human] [--output <file>]
 ----
 
 IMPORTANT: `--extracted` must be the property extractor's *raw* output (the `--output` file), never the enhanced output (`--enhanced-output`) or the versioned `redpanda-properties-<tag>.json` attachments: those already have overrides applied, so every override would classify as REDUNDANT. The same trap exists for rpk: the versioned `rpk-v<version>.json` files in docs repos are post-override snapshots.
@@ -133,7 +133,6 @@ JSON (default): `{ surface, overrides_file, extracted_file, manifest, summary, c
 
 * `properties` (complete): `property-overrides.json` vs the property extractor's raw JSON.
 * `rpk` (structural): enumerates `rpk-overrides.json` (see `docs-data/rpk-overrides.schema.json`) -- command/flag `description` fields are the upstreamable prose (classified `REVIEW` with a TODO note until source comparison lands; it needs a raw pre-override `--print-tree` snapshot plus the `formatDescription()` pipeline from `tools/rpk-docs`), everything else (`seeAlso`, `pageAliases`, `content`, platform scoping, ...) is `KEEP` by design.
-* `connect` (structural): enumerates the rp-connect-docs `overrides.json` (`definitions` + per-component arrays with nested `config.children`); prose fields classify `REVIEW` with a TODO note until `$ref` resolution and plugin-JSON comparison land.
 
 == Golden run (local checkouts required)
 

package/tools/overrides-audit/adapters/properties.js

@@ -4,7 +4,7 @@
  * Reads docs-data/property-overrides.json and an extracted-properties JSON
  * (the property extractor's raw --output, WITHOUT overrides applied) and
  * classifies every override field. This is the complete reference adapter;
- * rpk and connect adapters follow the same shape.
+ * The rpk adapter follows the same shape.
  */
 
 'use strict'

package/tools/overrides-audit/index.js

@@ -12,7 +12,7 @@
  *   node tools/overrides-audit/index.js \
  *     --overrides docs-data/property-overrides.json \
  *     --extracted tools/property-extractor/gen/properties-output.json \
- *     [--surface properties|rpk|connect] [--format json|human] [--output <file>]
+ *     [--surface properties|rpk] [--format json|human] [--output <file>]
  *
  * Also exposed as `doc-tools overrides audit` and the `audit_overrides`
  * MCP tool. See README.adoc in this directory for the classification rules
@@ -26,8 +26,7 @@ const path = require('path')
 
 const ADAPTERS = {
   properties: () => require('./adapters/properties'),
-  rpk: () => require('./adapters/rpk'),
-  connect: () => require('./adapters/connect')
+  rpk: () => require('./adapters/rpk')
 }
 
 /**
@@ -153,7 +152,7 @@ function main (argv) {
     .description('Classify docs-side override fields against extracted source strings')
     .requiredOption('--overrides <path>', 'Path to the overrides JSON file (for example docs-data/property-overrides.json)')
     .option('--extracted <path>', 'Path to the extracted source JSON (property extractor raw output; required for the properties surface)')
-    .option('--surface <surface>', 'Override surface: properties, rpk, or connect', 'properties')
+    .option('--surface <surface>', 'Override surface: properties or rpk', 'properties')
     .option('--format <format>', 'Output format: json or human', 'json')
     .option('--output <path>', 'Also write the JSON result to this file')
     .action((options) => {

package/tools/redpanda-connect/AUTOMATION.md

@@ -581,7 +581,7 @@ npx doc-tools generate rpcn-connector-docs \
 | `--draft-missing` | Generate full page drafts for new connectors | false |
 | `--update-whats-new` | Update whats-new.adoc with changes | false |
 | `--include-bloblang` | Include Bloblang functions/methods | false |
-| `--overrides <path>` | JSON file with description overrides | `docs-data/overrides.json` |
+| `--overrides <path>` | Optional JSON file with description overrides | None |
 
 ### Examples
 
@@ -766,41 +766,8 @@ Templates are in `tools/redpanda-connect/templates/`:
 - `connector-examples.hbs` - Examples template
 - `connector-full.hbs` - Full page draft template
 
-### Updating Overrides
-Override file: `docs-data/overrides.json` (or `--overrides` flag)
-
-```json
-{
-  "inputs": {
-    "kafka": {
-      "fields": {
-        "addresses": {
-          "description": "Custom description override",
-          "examples": ["localhost:9092"]
-        }
-      }
-    }
-  }
-}
-```
-
-Supports `$ref` syntax for deduplication:
-```json
-{
-  "inputs": {
-    "kafka": {
-      "fields": {
-        "tls": { "$ref": "#/common/tls" }
-      }
-    }
-  },
-  "common": {
-    "tls": {
-      "description": "TLS configuration (reused across components)"
-    }
-  }
-}
-```
+### Fixing connector descriptions
+Field, component, and Bloblang descriptions come from the component specs in `redpanda-data/connect` and `redpanda-data/benthos`. To fix wrong or missing text, open a PR against the spec. The fix ships in the next Connect release.
 
 ## Troubleshooting
 

package/tools/redpanda-connect/README.adoc

@@ -46,11 +46,6 @@ npm install @redpanda-data/docs-extensions-and-macros
 # Generate connector documentation with latest data
 npx doc-tools generate rpcn-connector-docs --fetch-connectors
 
-# Generate with custom overrides
-npx doc-tools generate rpcn-connector-docs \
-  --fetch-connectors \
-  --overrides path/to/overrides.json
-
 # Generate and draft missing connectors
 npx doc-tools generate rpcn-connector-docs \
   --fetch-connectors \
@@ -176,11 +171,6 @@ You can generate connector documentation with various options:
 # Basic generation with fetching latest data
 npx doc-tools generate rpcn-connector-docs --fetch-connectors
 
-# Generate with custom overrides for descriptions/examples
-npx doc-tools generate rpcn-connector-docs \
-  --fetch-connectors \
-  --overrides overrides.json
-
 # Draft full pages for connectors missing documentation
 npx doc-tools generate rpcn-connector-docs \
   --fetch-connectors \
@@ -202,7 +192,7 @@ npx doc-tools generate rpcn-connector-docs \
 * `--fetch-connectors` - Fetch latest data using `rpk connect list`
 * `--connect-version <version>` - Specific Connect version to install and fetch (requires `--fetch-connectors`)
 * `--draft-missing` - Generate full draft pages for undocumented connectors
-* `--overrides <path>` - Apply custom descriptions/examples from JSON
+* `--overrides <path>` - Merge descriptions and examples from an optional JSON file. Nothing is merged unless you pass it
 * `--data-dir <path>` - Directory containing versioned connect JSON files
 * `--old-data <path>` - Specific old version file for diff comparison
 * `--include-bloblang` - Include Bloblang functions/methods
@@ -791,7 +781,9 @@ console.log('<!-- PR_SUMMARY_END -->');
 
 === Override system
 
-Overrides allow customizing extracted documentation:
+Connector field, component, and Bloblang descriptions come from the component specs in https://github.com/redpanda-data/connect[redpanda-data/connect^] and https://github.com/redpanda-data/benthos[redpanda-data/benthos^]. To fix wrong or missing text, open a PR against the spec. The fix ships in the next Connect release.
+
+The generator can also merge an optional JSON file passed with `--overrides` into the extracted data. Nothing is merged unless you pass the flag:
 
 [,json]
 ----
@@ -840,11 +832,9 @@ Overrides support:
 * Connector catalog enrichment
 * Version tracking and change detection
 * Handlebars template rendering
-* Override system for custom documentation
 
 === Current limitations
 
-* *Manual override maintenance*: Custom descriptions must be maintained in overrides.json
 * *Example quality*: Auto-generated examples may not represent best practices
 * *Duplicate YAML keys*: Some examples contain multiple configurations in one block, creating invalid YAML with duplicate top-level keys (for example, multiple `processors:` keys)
 * *CSV catalog dependency*: Relies on manually maintained CSV in Connect repository
@@ -876,25 +866,7 @@ This occurs when multiple separate configurations are concatenated into a single
 
 === Workarounds
 
-For unsupported patterns or issues, use overrides.json:
-
-[,json]
-----
-{
-  "inputs": [
-    {
-      "name": "problematic_connector",
-      "description": "Custom description overriding auto-extracted text",
-      "examples": [
-        {
-          "title": "Corrected example",
-          "config": "input:\n  problematic_connector:\n    field: value"
-        }
-      ]
-    }
-  ]
-}
-----
+To fix an unsupported pattern, a wrong description, or a broken example, edit the component spec in redpanda-data/connect or redpanda-data/benthos. The fix ships in the next Connect release.
 
 == Contributing
 

package/tools/redpanda-connect/generate-rpcn-connector-docs.js

@@ -101,9 +101,9 @@ function mergeOverrides(target, overrides) {
     throw new Error('Target must be a valid object');
   }
 
-  // 'summary' earns its place here the hard way: overrides.json has carried
-  // summary overrides (zmq4, ffi) that were silently dropped because the key
-  // fell through every branch below. Summaries feed page meta descriptions.
+  // Scalar keys are replaced outright. 'summary' must be listed: a key that
+  // falls through every branch below is silently dropped, and summaries feed
+  // page meta descriptions.
   const scalarKeys = ['description', 'summary', 'type', 'annotated_field', 'version'];
 
   for (const key in overrides) {