Update ToolHive reference docs for v0.12.5 (#634)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

docs/toolhive/reference/crd-spec.md

@@ -538,6 +538,21 @@ _Appears in:_
 | `perWorkload` _object (keys:string, values:[vmcp.config.Duration](#vmcpconfigduration))_ | PerWorkload defines per-workload timeout overrides. |  | Optional: \{\} <br /> |
 
 
+#### vmcp.config.ToolAnnotationsOverride
+
+_Underlying type:_ _[vmcp.config.struct{Title *string "json:\"title,omitempty\" yaml:\"title,omitempty\""; ReadOnlyHint *bool "json:\"readOnlyHint,omitempty\" yaml:\"readOnlyHint,omitempty\""; DestructiveHint *bool "json:\"destructiveHint,omitempty\" yaml:\"destructiveHint,omitempty\""; IdempotentHint *bool "json:\"idempotentHint,omitempty\" yaml:\"idempotentHint,omitempty\""; OpenWorldHint *bool "json:\"openWorldHint,omitempty\" yaml:\"openWorldHint,omitempty\""}](#vmcpconfigstruct{title *string "json:\"title,omitempty\" yaml:\"title,omitempty\""; readonlyhint *bool "json:\"readonlyhint,omitempty\" yaml:\"readonlyhint,omitempty\""; destructivehint *bool "json:\"destructivehint,omitempty\" yaml:\"destructivehint,omitempty\""; idempotenthint *bool "json:\"idempotenthint,omitempty\" yaml:\"idempotenthint,omitempty\""; openworldhint *bool "json:\"openworldhint,omitempty\" yaml:\"openworldhint,omitempty\""})_
+
+ToolAnnotationsOverride defines overrides for tool annotation fields.
+All fields use pointers so nil means "don't override" while zero values
+(empty string, false) mean "explicitly set to this value."
+
+
+
+_Appears in:_
+- [vmcp.config.ToolOverride](#vmcpconfigtooloverride)
+
+
+
 #### vmcp.config.ToolConfigRef
 
 
@@ -559,7 +574,7 @@ _Appears in:_
 
 
 
-ToolOverride defines tool name and description overrides.
+ToolOverride defines tool name, description, and annotation overrides.
 
 
 
@@ -570,6 +585,7 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `name` _string_ | Name is the new tool name (for renaming). |  | Optional: \{\} <br /> |
 | `description` _string_ | Description is the new tool description. |  | Optional: \{\} <br /> |
+| `annotations` _[vmcp.config.ToolAnnotationsOverride](#vmcpconfigtoolannotationsoverride)_ | Annotations overrides specific tool annotation fields.<br />Only specified fields are overridden; others pass through from the backend. |  | Optional: \{\} <br /> |
 
 
 
@@ -2818,6 +2834,28 @@ _Appears in:_
 | `expiresInPath` _string_ | ExpiresInPath is the dot-notation path to the expires_in value (in seconds).<br />If not specified, defaults to "expires_in". |  | Optional: \{\} <br /> |
 
 
+#### api.v1alpha1.ToolAnnotationsOverride
+
+
+
+ToolAnnotationsOverride defines overrides for tool annotation fields.
+All fields use pointers so nil means "don't override" while zero values
+(empty string, false) mean "explicitly set to this value."
+
+
+
+_Appears in:_
+- [api.v1alpha1.ToolOverride](#apiv1alpha1tooloverride)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `title` _string_ | Title overrides the human-readable title annotation. |  | Optional: \{\} <br /> |
+| `readOnlyHint` _boolean_ | ReadOnlyHint overrides the read-only hint annotation. |  | Optional: \{\} <br /> |
+| `destructiveHint` _boolean_ | DestructiveHint overrides the destructive hint annotation. |  | Optional: \{\} <br /> |
+| `idempotentHint` _boolean_ | IdempotentHint overrides the idempotent hint annotation. |  | Optional: \{\} <br /> |
+| `openWorldHint` _boolean_ | OpenWorldHint overrides the open-world hint annotation. |  | Optional: \{\} <br /> |
+
+
 #### api.v1alpha1.ToolConfigRef
 
 
@@ -2853,6 +2891,7 @@ _Appears in:_
 | --- | --- | --- | --- |
 | `name` _string_ | Name is the redefined name of the tool |  | Optional: \{\} <br /> |
 | `description` _string_ | Description is the redefined description of the tool |  | Optional: \{\} <br /> |
+| `annotations` _[api.v1alpha1.ToolAnnotationsOverride](#apiv1alpha1toolannotationsoverride)_ | Annotations overrides specific tool annotation fields.<br />Only specified fields are overridden; others pass through from the backend. |  | Optional: \{\} <br /> |
 
 
 #### api.v1alpha1.UpstreamProviderConfig

static/api-specs/toolhive-api.yaml

@@ -326,6 +326,11 @@ components:
           description: 'HeaderStrategy determines how to inject the token: "replace"
             (default) or "custom".'
           type: string
+        provider_name:
+          description: |-
+            ProviderName identifies which upstream provider's tokens to retrieve for injection.
+            This is required and must match a configured upstream provider name.
+          type: string
       type: object
     github_com_stacklok_toolhive_pkg_authserver.OAuth2UpstreamRunConfig:
       description: |-
@@ -462,7 +467,7 @@ components:
           description: |-
             Upstreams configures connections to upstream Identity Providers.
             At least one upstream is required - the server delegates authentication to these providers.
-            Currently only a single upstream is supported.
+            Multiple upstreams are supported for sequential authorization chains.
           items:
             $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_authserver.UpstreamRunConfig'
           type: array
@@ -821,6 +826,23 @@ components:
           type: array
           uniqueItems: false
       type: object
+    github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig:
+      description: |-
+        AuthConfig contains the non-secret OAuth configuration when auth is configured.
+        Nil when auth_status is "none".
+      properties:
+        audience:
+          type: string
+        client_id:
+          type: string
+        issuer:
+          type: string
+        scopes:
+          items:
+            type: string
+          type: array
+          uniqueItems: false
+      type: object
     github_com_stacklok_toolhive_pkg_runner.HeaderForwardConfig:
       description: HeaderForward contains configuration for injecting headers into
         requests to remote servers.
@@ -961,6 +983,8 @@ components:
           type: string
         runtime_config:
           $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_container_templates.RuntimeConfig'
+        scaling_config:
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_runner.ScalingConfig'
         schema_version:
           description: SchemaVersion is the version of the RunConfig schema
           type: string
@@ -1027,6 +1051,24 @@ components:
           type: array
           uniqueItems: false
       type: object
+    github_com_stacklok_toolhive_pkg_runner.ScalingConfig:
+      description: |-
+        ScalingConfig contains configuration for horizontal scaling of the proxy runner.
+        Only applicable when running in Kubernetes with the ToolHive operator.
+        When nil, no scaling configuration is applied (single-replica default behavior).
+      properties:
+        backend_replicas:
+          description: |-
+            BackendReplicas is the desired StatefulSet replica count for the proxy runner backend.
+            When nil, replicas are unmanaged (preserving HPA or manual kubectl control).
+            When set (including 0), the value is an explicit replica count.
+          type: integer
+        session_cache_size:
+          description: |-
+            SessionCacheSize is the maximum number of sessions held in the local LRU cache.
+            When nil, consuming code applies a sensible default (e.g. 1000).
+          type: integer
+      type: object
     github_com_stacklok_toolhive_pkg_runner.ToolOverride:
       properties:
         description:
@@ -1365,6 +1407,25 @@ components:
       - RegistryTypeURL
       - RegistryTypeAPI
       - RegistryTypeDefault
+    pkg_api_v1.UpdateRegistryAuthRequest:
+      description: OAuth authentication configuration (optional)
+      properties:
+        audience:
+          description: OAuth audience (optional)
+          type: string
+        client_id:
+          description: OAuth client ID
+          type: string
+        issuer:
+          description: OIDC issuer URL
+          type: string
+        scopes:
+          description: OAuth scopes (optional)
+          items:
+            type: string
+          type: array
+          uniqueItems: false
+      type: object
     pkg_api_v1.UpdateRegistryRequest:
       description: Request containing registry configuration updates
       properties:
@@ -1374,6 +1435,8 @@ components:
         api_url:
           description: MCP Registry API URL
           type: string
+        auth:
+          $ref: '#/components/schemas/pkg_api_v1.UpdateRegistryAuthRequest'
         local_path:
           description: Local registry file path
           type: string
@@ -1588,6 +1651,18 @@ components:
     pkg_api_v1.getRegistryResponse:
       description: Response containing registry details
       properties:
+        auth_config:
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig'
+        auth_status:
+          description: |-
+            AuthStatus is one of: "none", "configured", "authenticated".
+            Intentionally omits omitempty — see registryInfo for rationale.
+          type: string
+        auth_type:
+          description: |-
+            AuthType is "oauth", "bearer" (future), or empty string when no auth.
+            Intentionally omits omitempty — see registryInfo for rationale.
+          type: string
         last_updated:
           description: Last updated timestamp
           type: string
@@ -1775,6 +1850,20 @@ components:
     pkg_api_v1.registryInfo:
       description: Basic information about a registry
       properties:
+        auth_config:
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig'
+        auth_status:
+          description: |-
+            AuthStatus is one of: "none", "configured", "authenticated".
+            Intentionally omits omitempty so clients always receive the field,
+            even when the value is "none" (the zero-value equivalent).
+          type: string
+        auth_type:
+          description: |-
+            AuthType is "oauth", "bearer" (future), or empty string when no auth.
+            Intentionally omits omitempty so clients can distinguish "no auth
+            configured" (empty string) from "field missing" without extra logic.
+          type: string
         last_updated:
           description: Last updated timestamp
           type: string
@@ -3037,6 +3126,62 @@ paths:
       summary: Get a server from a registry
       tags:
       - registry
+  /api/v1beta/registry/auth/login:
+    post:
+      description: Trigger an interactive OAuth flow to authenticate with the configured
+        registry. Only available in serve mode.
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                additionalProperties:
+                  type: string
+                type: object
+          description: Authenticated successfully
+        "400":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Bad Request - Registry OAuth not configured
+        "500":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Internal Server Error
+      summary: Registry login
+      tags:
+      - registry
+  /api/v1beta/registry/auth/logout:
+    post:
+      description: Clear cached OAuth tokens for the configured registry. Only available
+        in serve mode.
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                additionalProperties:
+                  type: string
+                type: object
+          description: Logged out successfully
+        "400":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Bad Request - Registry OAuth not configured
+        "500":
+          content:
+            application/json:
+              schema:
+                type: string
+          description: Internal Server Error
+      summary: Registry logout
+      tags:
+      - registry
   /api/v1beta/secrets:
     post:
       description: Setup the secrets provider with the specified type and configuration.