Update ToolHive reference docs for v0.22.0

docs/toolhive/reference/cli/thv_secret_delete.md

@@ -30,7 +30,8 @@ thv secret delete <name> [flags]
 ### Options
 
 ```
-  -h, --help   help for delete
+  -h, --help     help for delete
+      --system   Allow deleting a system-managed secret (emergency use only)
 ```
 
 ### Options inherited from parent commands

docs/toolhive/reference/cli/thv_secret_list.md

@@ -27,7 +27,8 @@ thv secret list [flags]
 ### Options
 
 ```
-  -h, --help   help for list
+  -h, --help     help for list
+      --system   List system-managed secrets (registry auth, workload tokens)
 ```
 
 ### Options inherited from parent commands

static/api-specs/crds/mcpexternalauthconfigs.schema.json

@@ -411,6 +411,14 @@
                   "oauth2Config": {
                     "description": "OAuth2Config contains OAuth 2.0-specific configuration.\nRequired when Type is \"oauth2\", must be nil when Type is \"oidc\".",
                     "properties": {
+                      "additionalAuthorizationParams": {
+                        "additionalProperties": {
+                          "type": "string"
+                        },
+                        "description": "AdditionalAuthorizationParams are extra query parameters to include in\nauthorization requests sent to the upstream provider.\nThis is useful for providers that require custom parameters, such as\nGoogle's access_type=offline for obtaining refresh tokens.\nFramework-managed parameters (response_type, client_id, redirect_uri,\nscope, state, code_challenge, code_challenge_method, nonce) are not allowed.",
+                        "maxProperties": 16,
+                        "type": "object"
+                      },
                       "authorizationEndpoint": {
                         "description": "AuthorizationEndpoint is the URL for the OAuth authorization endpoint.",
                         "pattern": "^https?://.*$",
@@ -552,6 +560,14 @@
                   "oidcConfig": {
                     "description": "OIDCConfig contains OIDC-specific configuration.\nRequired when Type is \"oidc\", must be nil when Type is \"oauth2\".",
                     "properties": {
+                      "additionalAuthorizationParams": {
+                        "additionalProperties": {
+                          "type": "string"
+                        },
+                        "description": "AdditionalAuthorizationParams are extra query parameters to include in\nauthorization requests sent to the upstream provider.\nThis is useful for providers that require custom parameters, such as\nGoogle's access_type=offline for obtaining refresh tokens.\nNote: when using access_type=offline, also set explicit scopes to avoid\nthe default offline_access scope being sent alongside it.\nFramework-managed parameters (response_type, client_id, redirect_uri,\nscope, state, code_challenge, code_challenge_method, nonce) are not allowed.",
+                        "maxProperties": 16,
+                        "type": "object"
+                      },
                       "clientId": {
                         "description": "ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.",
                         "type": "string"
@@ -584,7 +600,7 @@
                         "type": "string"
                       },
                       "scopes": {
-                        "description": "Scopes are the OAuth scopes to request from the upstream IDP.\nIf not specified, defaults to [\"openid\", \"offline_access\"].",
+                        "description": "Scopes are the OAuth scopes to request from the upstream IDP.\nIf not specified, defaults to [\"openid\", \"offline_access\"].\nWhen using additionalAuthorizationParams with provider-specific refresh token\nmechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid\nsending both offline_access and the provider-specific parameter.",
                         "items": {
                           "type": "string"
                         },

static/api-specs/crds/virtualmcpservers.schema.json

@@ -306,6 +306,14 @@
                   "oauth2Config": {
                     "description": "OAuth2Config contains OAuth 2.0-specific configuration.\nRequired when Type is \"oauth2\", must be nil when Type is \"oidc\".",
                     "properties": {
+                      "additionalAuthorizationParams": {
+                        "additionalProperties": {
+                          "type": "string"
+                        },
+                        "description": "AdditionalAuthorizationParams are extra query parameters to include in\nauthorization requests sent to the upstream provider.\nThis is useful for providers that require custom parameters, such as\nGoogle's access_type=offline for obtaining refresh tokens.\nFramework-managed parameters (response_type, client_id, redirect_uri,\nscope, state, code_challenge, code_challenge_method, nonce) are not allowed.",
+                        "maxProperties": 16,
+                        "type": "object"
+                      },
                       "authorizationEndpoint": {
                         "description": "AuthorizationEndpoint is the URL for the OAuth authorization endpoint.",
                         "pattern": "^https?://.*$",
@@ -447,6 +455,14 @@
                   "oidcConfig": {
                     "description": "OIDCConfig contains OIDC-specific configuration.\nRequired when Type is \"oidc\", must be nil when Type is \"oauth2\".",
                     "properties": {
+                      "additionalAuthorizationParams": {
+                        "additionalProperties": {
+                          "type": "string"
+                        },
+                        "description": "AdditionalAuthorizationParams are extra query parameters to include in\nauthorization requests sent to the upstream provider.\nThis is useful for providers that require custom parameters, such as\nGoogle's access_type=offline for obtaining refresh tokens.\nNote: when using access_type=offline, also set explicit scopes to avoid\nthe default offline_access scope being sent alongside it.\nFramework-managed parameters (response_type, client_id, redirect_uri,\nscope, state, code_challenge, code_challenge_method, nonce) are not allowed.",
+                        "maxProperties": 16,
+                        "type": "object"
+                      },
                       "clientId": {
                         "description": "ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.",
                         "type": "string"
@@ -479,7 +495,7 @@
                         "type": "string"
                       },
                       "scopes": {
-                        "description": "Scopes are the OAuth scopes to request from the upstream IDP.\nIf not specified, defaults to [\"openid\", \"offline_access\"].",
+                        "description": "Scopes are the OAuth scopes to request from the upstream IDP.\nIf not specified, defaults to [\"openid\", \"offline_access\"].\nWhen using additionalAuthorizationParams with provider-specific refresh token\nmechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid\nsending both offline_access and the provider-specific parameter.",
                         "items": {
                           "type": "string"
                         },
@@ -714,6 +730,11 @@
                   "description": "Component is the component name to use in audit events.",
                   "type": "string"
                 },
+                "detectApplicationErrors": {
+                  "default": true,
+                  "description": "DetectApplicationErrors controls whether the audit middleware inspects\nJSON-RPC response bodies for application-level errors when the HTTP\nstatus code indicates success (2xx). When enabled, a small prefix of\nthe response body is buffered to detect JSON-RPC error fields,\nindependent of the IncludeResponseData setting.",
+                  "type": "boolean"
+                },
                 "enabled": {
                   "default": false,
                   "description": "Enabled controls whether audit logging is enabled.\nWhen true, enables audit logging with the configured options.",
@@ -1957,7 +1978,7 @@
       "description": "VirtualMCPServerStatus defines the observed state of VirtualMCPServer",
       "properties": {
         "backendCount": {
-          "description": "BackendCount is the number of healthy/ready backends\n(excludes unavailable, degraded, and unknown backends)",
+          "description": "BackendCount is the number of routable backends (ready + unauthenticated).\nExcludes unavailable, degraded, and unknown backends.",
           "format": "int32",
           "type": "integer"
         },
@@ -2065,7 +2086,7 @@
                 "type": "string"
               },
               "status": {
-                "description": "Status is the current status of the backend (ready, degraded, unavailable, unknown).\nUse BackendHealthStatus.ToCRDStatus() to populate this field.",
+                "description": "Status is the current status of the backend (ready, degraded, unavailable, unauthenticated, unknown).\nUse BackendHealthStatus.ToCRDStatus() to populate this field.",
                 "type": "string"
               },
               "url": {

static/api-specs/toolhive-api.yaml

@@ -92,6 +92,16 @@ components:
             Component is the component name to use in audit events.
             +optional
           type: string
+        detectApplicationErrors:
+          description: |-
+            DetectApplicationErrors controls whether the audit middleware inspects
+            JSON-RPC response bodies for application-level errors when the HTTP
+            status code indicates success (2xx). When enabled, a small prefix of
+            the response body is buffered to detect JSON-RPC error fields,
+            independent of the IncludeResponseData setting.
+            +kubebuilder:default=true
+            +optional
+          type: boolean
         enabled:
           description: |-
             Enabled controls whether audit logging is enabled.
@@ -394,6 +404,14 @@ components:
         OAuth2Config contains OAuth 2.0-specific configuration.
         Required when Type is "oauth2", must be nil when Type is "oidc".
       properties:
+        additional_authorization_params:
+          additionalProperties:
+            type: string
+          description: |-
+            AdditionalAuthorizationParams are extra query parameters to include in
+            authorization requests. Useful for provider-specific parameters like
+            Google's access_type=offline.
+          type: object
         authorization_endpoint:
           description: AuthorizationEndpoint is the URL for the OAuth authorization
             endpoint.
@@ -436,6 +454,14 @@ components:
         OIDCConfig contains OIDC-specific configuration.
         Required when Type is "oidc", must be nil when Type is "oauth2".
       properties:
+        additional_authorization_params:
+          additionalProperties:
+            type: string
+          description: |-
+            AdditionalAuthorizationParams are extra query parameters to include in
+            authorization requests. Useful for provider-specific parameters like
+            Google's access_type=offline.
+          type: object
         client_id:
           description: ClientID is the OAuth 2.0 client identifier registered with
             the upstream IDP.
@@ -464,6 +490,9 @@ components:
           description: |-
             Scopes are the OAuth scopes to request from the upstream IDP.
             If not specified, defaults to ["openid", "offline_access"].
+            When using AdditionalAuthorizationParams with provider-specific refresh
+            token mechanisms (e.g., Google's access_type=offline), set explicit scopes
+            to avoid sending both offline_access and the provider-specific parameter.
           items:
             type: string
           type: array
@@ -876,6 +905,7 @@ components:
       - removing
       - unknown
       - unauthenticated
+      - policy_stopped
       - running
       - stopped
       - error
@@ -885,6 +915,7 @@ components:
       - removing
       - unknown
       - unauthenticated
+      - policy_stopped
       - running
       - stopped
       - error
@@ -894,6 +925,7 @@ components:
       - removing
       - unknown
       - unauthenticated
+      - policy_stopped
       type: string
       x-enum-varnames:
       - WorkloadStatusRunning
@@ -905,6 +937,7 @@ components:
       - WorkloadStatusRemoving
       - WorkloadStatusUnknown
       - WorkloadStatusUnauthenticated
+      - WorkloadStatusPolicyStopped
     github.com_stacklok_toolhive_pkg_container_templates.RuntimeConfig:
       description: |-
         RuntimeConfig allows overriding the default runtime configuration
@@ -924,7 +957,7 @@ components:
           description: |-
             BuilderImage is the full image reference for the builder stage.
             An empty string signals "use the default for this transport type" during config merging.
-            Examples: "golang:1.25-alpine", "node:22-alpine", "python:3.13-slim"
+            Examples: "golang:1.26-alpine", "node:24-alpine", "python:3.14-slim"
           type: string
       type: object
     github.com_stacklok_toolhive_pkg_core.Workload:
@@ -2209,6 +2242,10 @@ components:
         proxy_port:
           description: Port for the HTTP proxy to listen on
           type: integer
+        registry:
+          description: Registry is the optional registry name to resolve the server
+            from (e.g. "default").
+          type: string
         runtime_config:
           $ref: '#/components/schemas/github.com_stacklok_toolhive_pkg_container_templates.RuntimeConfig'
         secrets:
@@ -2217,6 +2254,13 @@ components:
             $ref: '#/components/schemas/github.com_stacklok_toolhive_pkg_secrets.SecretParameter'
           type: array
           uniqueItems: false
+        server:
+          description: |-
+            Server is the optional server name in the registry (e.g. "io.github.stacklok/fetch").
+            When both Registry and Server are set, thv resolves the server metadata
+            server-side, filling in image, transport, env vars, permissions, etc.
+            User-provided fields always override registry defaults.
+          type: string
         target_port:
           description: Port to expose from the container
           type: integer
@@ -4292,6 +4336,12 @@ paths:
               schema:
                 type: string
           description: Internal Server Error
+        "502":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Bad Gateway
       summary: Install a skill
       tags:
       - skills