@redpanda-data/docs-extensions-and-macros 5.54.0 → 5.56.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.56.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -33,6 +33,7 @@
     "test:cgo": "node __tests__/tools/cgo-detection.test.js",
     "test:all": "npm run test && npm run test:python && npm run test:cgo",
     "eval:doc-strings": "node evals/doc-strings/run-evals.js",
+    "eval:doc-impact": "node evals/doc-strings/run-evals.js --doc-impact",
     "generate:cli-docs": "node tools/generate-cli-docs.js",
     "bundle:admin": "doc-tools generate bundle-openapi --surface admin",
     "bundle:connect": "doc-tools generate bundle-openapi --surface connect",
@@ -94,7 +95,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",