Part 2: Update Registry Server docs for v1.0.0–v1.1.0 (#683)

* Update docs for ToolHive v0.17.0

Breaking changes:
- Update CRD phase values from Running to Ready for MCPServer,
  EmbeddingServer, and MCPRegistry across quickstarts, guides,
  and integration pages
- Migrate MCPRegistry examples from v1 flat registries[] format
  to v2 sources[]/registries[] with configYAML recommended path
- Remove PVC source type (no longer supported)
- Remove Syncing phase from MCPRegistry status documentation
- Remove auto-injection note for Kubernetes discovery sources

New features:
- Add MCPServerEntry (zero-infrastructure catalog entries) docs
  to K8s intro and vMCP configuration pages
- Add caBundleRef for OTLP endpoints to telemetry guide
- Add authServerRef for separating embedded auth from external
  token exchange to auth guide
- Update standalone registry server config to v2 format

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Address review findings from Copilot and code review

- Fix ConfigMap source example: use volumes/volumeMounts with file
  path instead of CRD-level configMapRef inside configYAML
- Fix URL source example: use file.url instead of CRD-level
  url.endpoint inside configYAML
- Fix file source docs: clarify file.path and file.url are mutually
  exclusive within the file block
- Add MCPServerEntry transport options (sse and streamable-http)
- Fix resource type count: "three" → "four" in K8s intro
- Align "running" → "ready" in vMCP quickstart preceding text

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update Registry Server docs for v1.0.0 and v1.0.1

Restructure configuration docs to reflect the new two-level config
model (sources + registries), add a dedicated authorization guide
covering RBAC roles and claims-based access control, and update all
related pages for cross-document consistency.

Key changes:
- Rewrite configuration.mdx for sources/registries split
- Add authorization.mdx (roles, claims, /v1/me endpoint)
- Replace claimMapping with authz-claims annotation docs
- Document skills sync from external sources
- Document multiple Kubernetes sources support
- Add DNS subdomain naming requirement for source names
- Update cross-references across deployment, skills, and intro pages
- Fix broken anchor in remote-mcp-proxy.mdx

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update Registry Server docs for v1.1.0 and address review findings

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix entries-without-claims visibility for auth-only mode

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Address PR review findings from Dan Barr

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Remove filler openers from front matter descriptions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Use upstream registry format in all examples

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Chris Burns <29541485+ChrisJBurns@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/toolhive/contributing.mdx

@@ -70,8 +70,9 @@ actively being developed and tested.
 ### Registry server
 
 The Registry Server is an API server that implements the official MCP Registry
-API. It provides standardized access to MCP servers from multiple backends,
-including file-based and other API-compliant registries.
+API. It provides standardized access to MCP servers and skills from multiple
+backends, including Git repositories, API endpoints, files, managed sources, and
+Kubernetes clusters.
 
 **Repository**:
 [stacklok/toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server)

docs/toolhive/guides-k8s/remote-mcp-proxy.mdx

@@ -801,7 +801,7 @@ Learn how to customize MCP tools using
 [filters and overrides](./customize-tools.mdx).
 
 Discover your deployed MCP servers automatically using the
-[Kubernetes registry](../guides-registry/configuration.mdx#kubernetes-registry)
+[Kubernetes source](../guides-registry/configuration.mdx#kubernetes-source)
 feature in the ToolHive Registry Server.
 
 ## Related information

docs/toolhive/guides-k8s/telemetry-and-metrics.mdx

@@ -175,7 +175,7 @@ spec:
 
 :::note
 
-`caBundleRef` cannot be used when `insecure` is set to `true` - they are
+`caBundleRef` cannot be used when `insecure` is set to `true` — they are
 mutually exclusive.
 
 :::

docs/toolhive/guides-registry/authentication.mdx

@@ -10,6 +10,14 @@ OAuth mode to protect your registry. You can configure authentication to fit
 different deployment scenarios, from development environments to production
 deployments with enterprise identity providers.
 
+:::tip[Looking for authorization?]
+
+This page covers **authentication** (verifying caller identity). For
+**authorization** (controlling what callers can do), including role-based access
+control and claims-based scoping, see [Authorization](./authorization.mdx).
+
+:::
+
 ## Authentication modes
 
 The server supports two authentication modes configured via the required `auth`
@@ -346,11 +354,14 @@ anonymous mode in production.**
 The following endpoints are **always accessible without authentication**,
 regardless of the auth mode:
 
-- `/health` - Health check endpoint
-- `/readiness` - Readiness probe endpoint
-- `/version` - Version information
+- `/openapi.json` - OpenAPI specification
 - `/.well-known/*` - OAuth discovery endpoints (RFC 9728)
 
+The `/health`, `/readiness`, and `/version` endpoints are served on a separate
+internal server (default port 8081) and are not exposed on the main API port.
+See the [command-line flags](./configuration.mdx#command-line-flags) for the
+`--internal-address` option.
+
 You can configure additional public paths using the `publicPaths` field in your
 OAuth configuration. See the
 [Registry API reference](../reference/registry-api.mdx) for complete endpoint
@@ -499,6 +510,14 @@ providers:
     caCertPath: /etc/ssl/certs/internal-ca.crt
 ```
 
+## Next steps
+
+- [Configure authorization](./authorization.mdx) to set up role-based access
+  control and claims-based scoping
+- [Set up the database](./database.mdx) for production storage and migrations
+- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and
+  metrics collection
+
 ## Troubleshooting
 
 ### 401 Unauthorized errors
@@ -544,9 +563,3 @@ If tokens from some providers work but others don't:
 4. Review server logs to identify which specific provider validation is failing
 5. Test each provider's JWKS endpoint accessibility:
    `curl ${issuerUrl}/.well-known/openid-configuration`
-
-## Next steps
-
-- [Set up the database](./database.mdx) for production storage and migrations
-- [Configure telemetry](./telemetry-metrics.mdx) for distributed tracing and
-  metrics collection