Update troubleshooting sections with collapsible blocks

Author: danbarr

.markdownlint.json

@@ -20,6 +20,9 @@
     "tables": false
   },
   "no-bare-urls": false,
+  "no-inline-html": {
+    "allowed_elements": ["details", "summary"]
+  },
   "proper-names": {
     "code_blocks": false,
     "names": ["Copilot", "GitHub", "ToolHive"]

docs/toolhive/guides-cli/client-configuration.md

@@ -160,7 +160,8 @@ ToolHive provides.
 
 ## Troubleshooting
 
-### Client is not detected by `thv client setup`
+<details>
+<summary>Client is not detected by `thv client setup`</summary>
 
 If ToolHive doesn't detect your client:
 
@@ -177,7 +178,10 @@ If ToolHive doesn't detect your client:
    thv config register-client <CLIENT_NAME>
    ```
 
-### Client can't connect to MCP server
+</details>
+
+<details>
+<summary>Client can't connect to MCP server</summary>
 
 If your client can't connect to the MCP server:
 
@@ -202,7 +206,10 @@ If your client can't connect to the MCP server:
 
 4. Restart your client application.
 
-### Client can connect but tools aren't available
+</details>
+
+<details>
+<summary>Client can connect but tools aren't available</summary>
 
 If your client connects to the MCP server but tools aren't available:
 
@@ -227,7 +234,10 @@ If your client connects to the MCP server but tools aren't available:
 5. If you've implemented authentication for your MCP server, make sure the
    client has the necessary permissions to access the tools.
 
-### Containerized client can't connect to MCP server
+</details>
+
+<details>
+<summary>Containerized client can't connect to MCP server</summary>
 
 If you're running an MCP client inside a container and it can't connect to an
 MCP server running on the same host, make sure you use the correct host address.
@@ -242,7 +252,10 @@ connectivity.
 Refer to your containerization platform's documentation for details on how to
 configure network access between containers and the host.
 
-### VS Code can't connect to some streamable-http servers
+</details>
+
+<details>
+<summary>VS Code can't connect to some streamable-http servers</summary>
 
 You might encounter errors with Visual Studio Code connecting to some
 Python-based MCP servers using the Streamable HTTP transport protocol:
@@ -267,3 +280,5 @@ There are two workarounds:
 
 You can track a proposed fix for this issue in the
 [MCP Python SDK repository](https://github.com/modelcontextprotocol/python-sdk/pull/781).
+
+</details>

docs/toolhive/guides-cli/custom-permissions.mdx

@@ -349,7 +349,8 @@ When creating and using permission profiles:
 
 ## Troubleshooting
 
-### File system access issues
+<details>
+<summary>File system access issues</summary>
 
 If your MCP server can't access the file system as expected:
 
@@ -365,7 +366,10 @@ If your MCP server can't access the file system as expected:
 
 4. Restart the server with the updated profile or a corrected volume mount
 
-### Network connectivity issues
+</details>
+
+<details>
+<summary>Network connectivity issues</summary>
 
 If your MCP server can't connect to external services:
 
@@ -381,3 +385,5 @@ If your MCP server can't connect to external services:
 
 4. Try temporarily using the default `network` profile to confirm it's a
    permissions issue
+
+</details>

docs/toolhive/guides-cli/install.mdx

@@ -49,6 +49,7 @@ available.
 1. Visit the [ToolHive releases page](https://github.com/stacklok/toolhive/releases)
 
 2. Download the appropriate binary for your platform:
+
    - `toolhive_<version>_darwin_amd64.tar.gz` for macOS (Intel)
    - `toolhive_<version>_darwin_arm64.tar.gz` for macOS (Apple Silicon)
    - `toolhive_<version>_linux_amd64.tar.gz` for Linux (x86_64)
@@ -323,7 +324,8 @@ MCP servers. See [Explore the registry](./registry.md) and
 
 ## Troubleshooting
 
-### Permission denied errors
+<details>
+<summary>Permission denied errors</summary>
 
 If you see "permission denied" errors when running ToolHive:
 
@@ -346,7 +348,10 @@ If you see "permission denied" errors when running ToolHive:
    [Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
    for more details.
 
-### Upgrade error on Windows
+</details>
+
+<details>
+<summary>Upgrade error on Windows</summary>
 
 If you encounter an error when upgrading ToolHive on Windows, it may be due to
 the ToolHive executable being locked by a running MCP server proxy.
@@ -383,6 +388,8 @@ To resolve this:
    # repeat for each server
    ```
 
+</details>
+
 ### Other issues
 
 For other installation issues, check the

docs/toolhive/guides-cli/run-mcp-servers.mdx

@@ -383,7 +383,8 @@ control your servers.
 
 ## Troubleshooting
 
-### Server fails to start
+<details>
+<summary>Server fails to start</summary>
 
 If a server fails to start:
 
@@ -392,7 +393,10 @@ If a server fails to start:
 3. Check if the port is already in use
 4. Look at the error message for specific issues
 
-### Server starts but isn't accessible
+</details>
+
+<details>
+<summary>Server starts but isn't accessible</summary>
 
 If a server starts but isn't accessible:
 
@@ -407,7 +411,10 @@ If a server starts but isn't accessible:
 3. Make sure clients are properly configured (see
    [Client configuration](client-configuration.md))
 
-### Server crashes or exits unexpectedly
+</details>
+
+<details>
+<summary>Server crashes or exits unexpectedly</summary>
 
 If a server crashes or exits unexpectedly:
 
@@ -430,3 +437,5 @@ If a server crashes or exits unexpectedly:
    ```
 
 4. Check if the server requires any secrets or environment variables
+
+</details>

docs/toolhive/guides-cli/secrets-management.mdx

@@ -278,7 +278,8 @@ in the `MCPVault` vault and passes them to the `slack` MCP server as the
 
 ## Troubleshooting
 
-### Keyring access issues
+<details>
+<summary>Keyring access issues</summary>
 
 If you run into errors related to the system keyring:
 
@@ -294,7 +295,10 @@ If you run into errors related to the system keyring:
    sudo dnf install gnome-keyring
    ```
 
-### Secret not available to MCP server
+</details>
+
+<details>
+<summary>Secret not available to MCP server</summary>
 
 If your MCP server can't access a secret:
 
@@ -324,13 +328,19 @@ If your MCP server can't access a secret:
    thv logs <server-name>
    ```
 
-### Forgot encryption password
+</details>
+
+<details>
+<summary>Forgot encryption password</summary>
 
 If the keyring entry is lost or corrupted and you forget your encryption
 password, you won't be able to access your secrets. In this case, delete the
 [encrypted secrets file](#reset-your-secret-store) and recreate your secrets.
 
-### Issues accessing 1Password secrets
+</details>
+
+<details>
+<summary>Issues accessing 1Password secrets</summary>
 
 If you can't access 1Password secrets:
 
@@ -353,3 +363,5 @@ If you can't access 1Password secrets:
    ```bash
    thv secret get op://<vault-name>/<item-name>/[section-name/]<field-name>
    ```
+
+</details>

docs/toolhive/guides-k8s/deploy-operator-helm.md

@@ -246,7 +246,8 @@ configured during installation.
 
 ## Troubleshooting
 
-### Authentication error with ghcr.io
+<details>
+<summary>Authentication error with ghcr.io</summary>
 
 If you encounter an authentication error when pulling the Helm chart, it might
 indicate a problem with your access to the GitHub Container Registry
@@ -259,7 +260,10 @@ your token has expired or been revoked.
 See the GitHub documentation to
 [re-authenticate to the registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic).
 
-### Operator pod fails to start
+</details>
+
+<details>
+<summary>Operator pod fails to start</summary>
 
 If the operator pod is not starting or is in a `CrashLoopBackOff` state, check
 the pod logs for error messages:
@@ -284,7 +288,10 @@ Common causes include:
   resources available
 - **Image pull issues**: Verify that the cluster can pull images from `ghcr.io`
 
-### CRDs installation fails
+</details>
+
+<details>
+<summary>CRDs installation fails</summary>
 
 If the CRDs installation fails, you might see errors about existing resources or
 permission issues:
@@ -304,7 +311,10 @@ helm uninstall toolhive-operator-crds
 helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
 ```
 
-### Namespace creation issues
+</details>
+
+<details>
+<summary>Namespace creation issues</summary>
 
 If you encounter permission errors when creating the `toolhive-system`
 namespace, create it manually first:
@@ -319,7 +329,10 @@ Then install the operator without the `--create-namespace` flag:
 helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system
 ```
 
-### Helm chart not found
+</details>
+
+<details>
+<summary>Helm chart not found</summary>
 
 If Helm cannot find the chart, ensure you're using the correct OCI registry URL
 and that your Helm version supports OCI registries (v3.8.0+):
@@ -332,10 +345,15 @@ helm version
 helm pull oci://ghcr.io/stacklok/toolhive/toolhive-operator
 ```
 
-### Network connectivity issues
+</details>
+
+<details>
+<summary>Network connectivity issues</summary>
 
 If you're experiencing network timeouts or connection issues:
 
 - Verify your cluster has internet access to reach `ghcr.io`
 - Check if your organization uses a proxy or firewall that might block access
 - Consider using a private registry mirror if direct access is restricted
+
+</details>