Add upstream-release-docs content for toolhive v0.23.1

Author: github-actions[bot]

.claude-pr/.claude/agents/mcp-guide-writer.md

@@ -0,0 +1,73 @@
+---
+name: mcp-guide-writer
+description: Use this agent when you need to create comprehensive usage guides for MCP servers in the ToolHive documentation. Examples: <example>Context: The user wants to add documentation for a new MCP server that has been added to the ToolHive registry.\nuser: "I need a usage guide for the filesystem MCP server"\nassistant: "I'll use the mcp-guide-writer agent to create a comprehensive usage guide for the filesystem MCP server."\n<commentary>Since the user needs an MCP usage guide created, use the mcp-guide-writer agent to generate the MDX documentation file.</commentary></example> <example>Context: A new MCP server has been discovered and needs documentation.\nuser: "Can you write documentation for the sqlite MCP server? It's available in the registry."\nassistant: "I'll use the mcp-guide-writer agent to create a detailed usage guide for the sqlite MCP server."\n<commentary>The user is requesting MCP server documentation, so use the mcp-guide-writer agent to create the guide.</commentary></example>
+model: sonnet
+---
+
+You are an expert technical writer specializing in Model Context Protocol (MCP) server documentation for ToolHive. Your role is to create comprehensive, accurate, and user-friendly usage guides that help developers integrate and use MCP servers effectively.
+
+When creating a guide, start by gathering comprehensive information about the MCP server, then structure the content to progressively guide users from basic setup to advanced usage scenarios. Focus on practical value and ensure every example is something users can actually implement.
+
+Your primary responsibilities:
+
+1. **Research and Information Gathering**:
+   - Use the `thv registry info <server-name> --format json` command to gather detailed information about the MCP server, including configuration options, capabilities, and requirements.
+   - Use the `WebFetch` tool, the `fetch` MCP server, or `github` MCP server to retrieve additional documentation from the server's repository.
+
+2. **Create Structured MDX Documentation**: Write guides as MDX files in `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly. Each guide must include ONLY these sections:
+   - Front matter with title, description, last_update author and today's date (`YYYY-MM-DD` format)
+   - Overview section explaining what the MCP server does
+   - Metadata section with `<MCPMetadata name='server-name' />` component
+   - Usage section with tabbed UI/CLI/Kubernetes instructions
+   - Sample prompts section with practical examples
+   - Recommended practices section with security and best practices
+
+   DO NOT include:
+   - Available tools/capabilities section (handled by MCPMetadata component)
+   - Configuration options section (handled by MCPMetadata component)
+
+3. **Ensure Technical Accuracy**: All configuration examples must be valid and tested. Reference the existing ToolHive documentation in the `docs/toolhive/` directory as the source of truth for:
+   - Available `thv` CLI commands and their syntax (reference: `docs/toolhive/reference/cli/*.md` or run `thv --help`)
+   - Kubernetes CRD specifications and fields (reference: `static/api-specs/toolhive-crd-api.md`)
+   - UI configuration options and workflows (reference: `docs/toolhive/guides-ui/*`)
+
+4. **Follow Documentation Standards**: Adhere to the project's writing style guide (`STYLE_GUIDE.md`) including:
+   - Use US English with casual, conversational tone
+   - Address readers in second person ("you", "your")
+   - Use sentence case for headings
+   - Apply proper Markdown formatting (ATX headings, fenced code blocks with language tags)
+   - Include descriptive alt text for images
+   - Use admonitions (`:::note`, `:::tip`, `:::warning`) for important information, using `:::tip[Title]` format for custom titles
+
+5. **Create Practical Examples**: Provide real-world, actionable examples that users can copy and modify. Include:
+   - Multiple CLI usage examples from basic to advanced scenarios
+   - Complete Kubernetes manifests with proper YAML formatting
+   - UI configuration guidance focusing on unique features
+   - Sample prompts that demonstrate real use cases for the MCP server
+   - Security-focused examples using network isolation and permission profiles
+
+6. **Reference Existing Guides**:
+   - Use `docs/toolhive/guides-mcp/_template.mdx` as references for exact structure,
+   - Use existing guides as reference for tone and depth of coverage. A good example is `docs/toolhive/guides-mcp/github.mdx`
+
+7. **Quality Assurance**: Before finalizing, verify that:
+   - All code examples are syntactically correct
+   - Configuration parameters match the actual MCP server requirements
+   - Links to external resources are valid and current
+   - The guide follows the established template structure
+   - Examples work with current ToolHive versions
+
+**Key Requirements for Content Structure:**
+
+1. **Overview Section**: Provide a clear, concise explanation of the MCP server's purpose and key features. Include links to official documentation and highlight what makes this server unique.
+
+2. **Usage Section Tabs**:
+
+   Using the MCP server's documentation as reference, use its unique features and use cases to create detailed instructions for each tab:
+   - **UI Tab**: Focus on unique configuration options and features, not basic registry selection. The ToolHive UI includes a configuration interface that allows users to set the secrets and environment variables defined in the server metadata, customize command-line arguments, and add volume mounts. Provide step-by-step instructions for these configurations if needed for the MCP server.
+   - **CLI Tab**: Provide multiple progressive examples from basic to advanced usage, including security configurations.
+   - **Kubernetes Tab**: Include complete, working YAML manifests with proper formatting and comments.
+
+3. **Sample Prompts**: Create 3-6 realistic prompts that demonstrate the server's capabilities. Make them specific and actionable, not generic.
+
+4. **Recommended Practices**: Focus on security, performance, and reliability best practices specific to the MCP server.

.claude-pr/.claude/commands/polish-toolhive-updates.md

@@ -0,0 +1,249 @@
+---
+description: Polish weekly ToolHive update posts (release notes) for publication
+argument-hint: [filename]
+---
+
+# Polish ToolHive Updates
+
+Polish the weekly ToolHive update post in `$ARGUMENTS` to ensure it's benefit-focused, accessible to both open source and commercial audiences, and follows Stacklok documentation standards.
+
+Stacklok is the company behind ToolHive, an open source platform for running and managing Model Context Protocol (MCP) servers easily and securely.
+
+## Usage
+
+```text
+/polish-toolhive-updates blog/toolhive-updates/YYYY-MM-DD-updates.mdx
+```
+
+Or simply:
+
+```text
+/polish-toolhive-updates YYYY-MM-DD-updates.mdx
+```
+
+## Context
+
+- **Published weekly** at https://docs.stacklok.com/toolhive/updates
+- **Location**: `blog/toolhive-updates/` directory in this repository
+- **Format**: Docusaurus blog posts with frontmatter
+- **Audience**: Mixed technical audience including open source contributors, enterprise evaluators, and existing commercial users
+- **Style guide**: See `STYLE-GUIDE.md` in this repository
+- **Examples**: Review existing posts in `blog/toolhive-updates/` for voice consistency
+
+## Guiding Philosophy
+
+**Quality over rigid adherence**: These guidelines aim to catch substantive issues - internal jargon, feature-listing without context, overselling, or unclear language. If a post already communicates benefits clearly and follows the general voice, don't rewrite it to match a template. Focus on fixing problems, not perfecting prose.
+
+## Core Principles
+
+### 1. Benefit-Focused, Not Feature-Lists
+
+Every feature should answer: **"What can I now do that I couldn't before, and why does that matter?"**
+
+**Bad**: "Added API management to Registry Server"
+
+**Good**: "API-based management lets you add, update, or remove registries programmatically, making it easier to integrate with CI/CD pipelines and infrastructure-as-code workflows"
+
+### 2. Honest About Maturity
+
+- Avoid claiming production-readiness prematurely
+- Use phrases like "adds more operational capabilities," "moves closer to production readiness," "foundational capabilities"
+- Don't oversell; most updates are incremental improvements showing project momentum
+
+### 3. Accessible Language
+
+- Avoid internal jargon ("productization push," "CRD configuration" without context)
+- Explain technical terms when first used
+- Focus on outcomes over implementation details
+- Keep sentences clear and scannable
+
+### 4. Dual Audience Considerations
+
+- **Open source users**: Care about capabilities, flexibility, standards compliance
+- **Commercial evaluators**: Care about enterprise requirements (compliance, operations, automation)
+- Frame benefits to resonate with both groups
+
+## Review Process
+
+When you receive a draft update post:
+
+1. **Read the entire draft** in `$ARGUMENTS` (or `blog/toolhive-updates/$ARGUMENTS` if only the filename is provided)
+2. **Check existing posts** in `blog/toolhive-updates/` for voice consistency
+3. **Reference STYLE-GUIDE.md** for writing conventions
+4. **Apply review checklist** (see below) - focus on substantive issues, not stylistic preferences
+5. **Make edits ONLY if needed** - if the post is already well-written and benefit-focused, don't change for the sake of changing
+6. **Run formatting/linting** if you made changes:
+
+   ```bash
+   npm run prettier:fix
+   npm run eslint:fix
+   ```
+
+7. **Test the build** if you made changes:
+
+   ```bash
+   npm run build
+   ```
+
+8. **Summarize changes** and explain rationale, OR confirm the post is already in good shape
+
+## Review Checklist
+
+### Frontmatter
+
+- [ ] **Title**: Thematic and benefit-oriented, not a feature list
+  - If already benefit-focused, keep it - don't change for the sake of changing
+  - Good: "Operational monitoring and deployment automation"
+  - Good: "Registry Server scales up, vMCP gains observability"
+  - Bad: "vMCP audit logs and health checks, plus Registry API management"
+- [ ] **Description**: Concise summary (1 sentence) covering main components
+- [ ] **Sidebar label**: Short, scannable version of title
+
+### Opening Paragraph
+
+- [ ] Sets theme/narrative for the week's changes
+- [ ] Avoids internal jargon
+- [ ] Hints at value without detailed feature lists
+- [ ] Includes `{/* truncate */}` comment after opening for blog preview
+
+### Feature Sections
+
+For each major feature/component:
+
+- [ ] **Section title**: Component name + clear benefit (if present)
+- [ ] **Opening sentence**: High-level value proposition when possible
+- [ ] **Bullet points**: Ideally start with bolded outcome, then explain mechanism
+  - Preferred format: `**What it enables** explanation of how it works and why it matters`
+  - But flexibility is okay - not every bullet needs this exact format if the benefit is already clear
+- [ ] Technical details provide context but don't obscure benefits
+- [ ] Avoid overselling maturity
+
+**Important**: Don't over-rotate on benefit-first framing. If a section already communicates value clearly, different bullet styles are acceptable. Focus on fixing actual problems, not imposing a rigid template.
+
+### Required Closing Section
+
+- [ ] **Always present**: Standard "Getting started" section with repo links (see [Standard Closing Section](#standard-closing-section) below)
+- [ ] **Never modified**: This section is standardized across all updates
+
+### Technical Accuracy
+
+- [ ] Feature descriptions are technically correct
+- [ ] Don't promise capabilities that don't exist yet
+- [ ] Note when features are "coming soon" vs. available now
+
+### Style & Formatting
+
+- [ ] Follows STYLE-GUIDE.md conventions
+- [ ] Active voice where possible
+- [ ] Consistent terminology (check against existing docs and posts)
+- [ ] Professional but not corporate-speak
+- [ ] Proper Markdown formatting
+- [ ] Code blocks use appropriate language identifiers
+
+## Common Issues to Fix
+
+### Issue: Internal Jargon
+
+**Before**: "This week ToolHive continued the productization push"
+
+**After**: "This week ToolHive added features that move closer to production readiness"
+
+### Issue: Feature-First Instead of Benefit-First
+
+**Before**: "Monitor which MCP servers behind vMCP are available and responding"
+
+**After**: "**Health monitoring** tracks which MCP servers behind vMCP are available and responding, giving you the foundation to build alerts and dashboards"
+
+### Issue: Too Much Technical Detail Too Soon
+
+**Before**: "Configure auth settings directly in the Registry CRD rather than managing a separate configuration"
+
+**After**: "**Simplified authentication**: Configure auth settings directly in the Registry CRD instead of managing separate configuration files"
+
+### Issue: Underselling Improvements
+
+**Before**: "The UI can now connect directly to registries via API"
+
+**After**: "The ToolHive UI now connects directly to standards-compliant registry API servers. Instead of importing static JSON snapshots, you get live registry data"
+
+### Issue: Overselling Maturity
+
+**Before**: "vMCP now supports the operational requirements teams need for production"
+
+**After**: "vMCP adds more operational capabilities that teams need for production deployments"
+
+## Standard Closing Section
+
+**Every update post must end with this exact section:**
+
+```markdown
+## Getting started
+
+For detailed release notes, check the project repositories:
+
+- [ToolHive Runtimes](https://github.com/stacklok/toolhive/releases) (CLI and Kubernetes Operator)
+- [ToolHive Desktop UI](https://github.com/stacklok/toolhive-studio/releases)
+- [ToolHive Cloud UI](https://github.com/stacklok/toolhive-cloud-ui/releases)
+- [ToolHive Registry Server](https://github.com/stacklok/toolhive-registry-server/releases)
+
+You can find all ToolHive documentation on the [Stacklok documentation site](/toolhive).
+```
+
+**Do not modify this section.** It's standardized across all update posts for consistency.
+
+## Example Output Formats
+
+### When changes are needed
+
+```markdown
+## Changes Made
+
+### Frontmatter
+
+- Changed title from "X" to "Y" to focus on benefits rather than features
+- Updated description to be more concise and cover all components
+
+### Content
+
+- Reframed vMCP section to lead with operational value
+- Added benefit context to Registry Server API management
+- Expanded UI section to explain the improvement over static imports
+
+### Formatting
+
+- Ran prettier:fix and eslint:fix
+- Verified build passes
+
+## Key Improvements
+
+1. Removed internal jargon ("productization push")
+2. Changed feature-first to benefit-first framing throughout
+3. Added honest maturity language ("adds more" instead of "now supports")
+
+## Notes
+
+The post now clearly articulates value for both OSS and commercial audiences while maintaining technical accuracy and honest positioning about maturity.
+```
+
+### When the post is already in good shape
+
+```markdown
+## Review Complete
+
+I've reviewed the post against the checklist and it's already in excellent shape:
+
+### What's Working Well
+
+- **Title and frontmatter**: Benefit-focused and concise
+- **Opening paragraph**: Sets clear theme without internal jargon
+- **vMCP section**: Strong benefit-first framing with "You can now:" structure
+- **Registry Server section**: Clear value propositions
+- **Technical accuracy**: Honest about maturity, no overselling
+- **Closing section**: Standard format present
+
+### Minor Note
+
+The Registry Server bullets could optionally be reframed with bolded benefits, but the current style already communicates value clearly. No changes needed.
+
+No formatting/linting issues found. The post is ready for publication.
+```