Update operator architecture documentation for authServerRef

[tgrunnagle]

Description

Update the operator architecture documentation (docs/arch/09-operator-architecture.md) to describe the new authServerRef field, its role as the dedicated incoming auth reference (embedded auth server), its relationship to externalAuthConfigRef (outgoing auth), and the combined configuration pattern. Also regenerate the CRD API reference docs so the new fields appear in the auto-generated documentation.

Context

RFC-0050 adds a new authServerRef field to both MCPServerSpec and MCPRemoteProxySpec that separates the embedded auth server (incoming auth) from externalAuthConfigRef (outgoing auth). After #4640 lands the CRD types, controller logic, and unit tests, the architecture documentation needs to reflect these changes so developers and operators understand the new field, when to use it, and how it composes with outgoing auth types.

The existing docs/arch/09-operator-architecture.md documents both MCPServer and MCPRemoteProxy CRDs, including their key fields and configuration references. It currently has no mention of authServerRef or the incoming vs outgoing auth distinction. The CRD API reference docs at docs/operator/crd-api.md are auto-generated from Go type comments and need regeneration after the CRD type changes.

Dependencies: #4640 (CRD types, controller logic, and unit tests)
Blocks: None

Acceptance Criteria

• docs/arch/09-operator-architecture.md describes the authServerRef field on both MCPServer and MCPRemoteProxy
• Documentation explains authServerRef as the dedicated incoming auth reference (embedded auth server) distinct from externalAuthConfigRef (outgoing auth)
• Documentation describes the combined configuration pattern (e.g., authServerRef for embedded auth server + externalAuthConfigRef for AWS STS on the same resource)
• Documentation mentions conflict detection (both fields pointing to embedded auth server produces an error)
• Documentation notes backward compatibility: existing externalAuthConfigRef with type: embeddedAuthServer continues to work
• The CRD relationships Mermaid diagram in 09-operator-architecture.md includes authServerRef edges from MCPServer and MCPRemoteProxy to MCPExternalAuthConfig
• CRD API reference docs regenerated via task crdref-gen (from cmd/thv-operator/)
• All existing documentation links and cross-references remain intact
• Code reviewed and approved

Technical Approach

Recommended Implementation

The documentation updates focus on three areas within docs/arch/09-operator-architecture.md:

1. MCPServer section (around line 139-158): Add authServerRef to the list of supported configuration references, alongside the existing oidcConfigRef, telemetryConfigRef, and externalAuthConfigRef entries. Explain that authServerRef is the preferred path for configuring the embedded OAuth 2.0/OIDC authorization server (incoming auth), while externalAuthConfigRef is used for outgoing auth types (token exchange, AWS STS, bearer token injection, etc.).

2. MCPRemoteProxy section (around line 243-258): Add authServerRef to the key fields list. This is the primary use case -- enabling the embedded auth server alongside AWS STS request signing on the same proxy resource. Include a brief YAML snippet showing the combined pattern.

3. CRD Relationships Mermaid diagram (around line 102-137): Add authServerRef edges from both Server and Proxy nodes to the ExtAuth configuration node, using a distinct line style (e.g., dotted with different annotation) to visually distinguish it from externalAuthConfigRef.

4. MCPExternalAuthConfig section (around line 185-195): Update the description to note that MCPExternalAuthConfig resources can now be referenced via two paths: externalAuthConfigRef for outgoing auth types, and authServerRef for the embedded auth server type.

After documentation edits, regenerate the CRD API reference by running task crdref-gen from the cmd/thv-operator/ directory. This produces docs/operator/crd-api.md with the new authServerRef and authServerConfigHash fields documented from Go type comments added in #4640.

Patterns & Frameworks

• Follow the existing documentation style in docs/arch/09-operator-architecture.md -- concise descriptions with code references and YAML examples
• Use Mermaid diagram syntax consistent with the existing CRD relationships diagram
• Follow the architecture documentation guidelines from docs/arch/README.md: start with "why", include code references, add diagrams, and cross-reference related documents
• Reference RFC-0050 for detailed design rationale

Code Pointers

• docs/arch/09-operator-architecture.md (lines 139-158) - MCPServer section where authServerRef description should be added alongside existing config refs
• docs/arch/09-operator-architecture.md (lines 243-258) - MCPRemoteProxy section where authServerRef and combined auth pattern should be documented
• docs/arch/09-operator-architecture.md (lines 102-137) - CRD Relationships Mermaid diagram needing authServerRef edges
• docs/arch/09-operator-architecture.md (lines 185-195) - MCPExternalAuthConfig section needing dual-reference-path note
• docs/operator/crd-api.md - Auto-generated CRD API reference docs (regenerated, not hand-edited)
• cmd/thv-operator/Taskfile.yml (line 280) - crdref-gen task definition
• docs/proposals/THV-0050-embedded-as-with-aws-sts.md - RFC-0050 with full design rationale

Component Interfaces

No new code interfaces. This task produces documentation changes only.

Example YAML snippet for the combined auth pattern documentation:

# MCPRemoteProxy with embedded auth server (incoming) + AWS STS (outgoing)
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRemoteProxy
metadata:
  name: bedrock-proxy
spec:
  remoteURL: https://bedrock-mcp.example.com
  authServerRef:
    apiGroup: toolhive.stacklok.dev
    kind: MCPExternalAuthConfig
    name: my-auth-server          # type: embeddedAuthServer
  externalAuthConfigRef:
    name: bedrock-sts-config      # type: awsSts

Testing Strategy

Manual Verification

• Confirm docs/arch/09-operator-architecture.md renders correctly (Mermaid diagrams, YAML snippets, cross-references)
• Confirm task crdref-gen completes without errors and docs/operator/crd-api.md includes authServerRef and authServerConfigHash field documentation
• Confirm no broken links or cross-references in the updated documentation

No automated tests -- this is a documentation-only task.

Out of Scope

• User-facing documentation updates in stacklok/docs-website (covered by fix(deps): update module github.com/lmittmann/tint to v1.1.2 #671)
• Changes to CRD types, controller logic, or unit tests (completed in Add authServerRef CRD types, controller logic, and unit tests #4640)
• E2E tests (covered by Add E2E tests for authServerRef on MCPServer and MCPRemoteProxy #4641)
• Any code changes beyond documentation and CRD reference regeneration

References

• RFC-0050: Dedicated Auth Server Reference for MCP Resources
• Operator Architecture Documentation
• CRD API Reference Docs
• Architecture Documentation Guidelines