docs: comprehensive documentation overhaul

[ian-flores]

Summary

This PR addresses the documentation gaps identified during a comprehensive review of the Team Operator documentation. The review found several critical issues including broken links, missing guides, undocumented features, and inconsistent terminology.

New Documentation Created

Product Configuration Guides:

• docs/guides/workbench-configuration.md - Complete Workbench setup including off-host execution, IDEs, data integrations
• docs/guides/connect-configuration.md - Connect configuration with GPU support, sessions, Chronicle integration
• docs/guides/packagemanager-configuration.md - Package Manager with S3, Azure Files, Git SSH keys

Core Guides:

• docs/guides/authentication-setup.md - OIDC/SAML/Password authentication with IdP examples (Okta, Azure AD, Auth0)
• docs/guides/product-team-site-management.md - Site CRD lifecycle and configuration
• docs/guides/troubleshooting.md - Comprehensive troubleshooting for all components
• docs/guides/upgrading.md - Upgrade procedures, migrations, rollback

Reference Documentation:

• docs/api-reference.md - Complete CRD API reference with field tables
• dist/chart/README.md - Helm chart documentation with all values
• CONTRIBUTING.md - Contributor guidelines and development setup

Improvements to Existing Documentation

• README.md: Added table of contents, fixed architecture diagrams (applied unused styling), completed Site CR example
• docs/README.md: Added 4 new architecture diagrams (system overview, reconciliation flow, Workbench architecture, component relationships), comprehensive guide navigation
• api/keycloak/v2alpha1/README.md: Expanded from 7 lines to useful documentation
• CLAUDE.md: Updated project structure and commands

Issues Resolved

• Fixed broken links to non-existent docs/guides/ directory
• Clarified namespace usage (posit-team-system vs posit-team)
• Documented all previously undocumented features (experimental features, GPU support, data integrations)

Test Plan

• Verify all internal links work correctly
• Review diagrams render properly on GitHub
• Confirm examples are copy-paste ready
• Check namespace references are consistent throughout

[claude]

Claude finished @ian-flores's task —— View job

---

Documentation Review Complete

• Read review guidelines from .claude/review-guidelines.md
• Analyze the PR diff and changed files
• Review documentation changes for accuracy and completeness
• Create and submit PR review with inline comments

Summary: Reviewed this comprehensive documentation overhaul covering 15 files with 8,500+ lines of new documentation. The PR significantly improves the operator's documentation with:

• New architecture diagrams (Mermaid)
• Product configuration guides (Workbench, Connect, Package Manager)
• Authentication setup guide with IdP examples
• Comprehensive troubleshooting guide
• Helm chart documentation
• Contributor guidelines

Submitted review with minor suggestions including: verifying API group consistency, checking Go version in CONTRIBUTING.md, and confirming version references in the upgrade guide.

[claude]

Documentation Review

This is a substantial and well-organized documentation overhaul that significantly improves the operator's documentation. The PR addresses critical gaps and provides comprehensive guides for users and contributors.

Highlights

Strong additions:

• The Mermaid architecture diagrams in docs/README.md are excellent - the reconciliation flow and system architecture visualizations greatly improve understanding
• The troubleshooting guide (docs/guides/troubleshooting.md) is comprehensive with a particularly useful "Common Error Messages" table
• The contributor guide for adding config options (docs/guides/adding-config-options.md) has actionable step-by-step instructions with code examples
• The authentication setup guide covers multiple IdPs (Okta, Azure AD, Auth0, Keycloak) which is very practical
• The Helm chart README provides a complete configuration reference with good examples

Items to Verify

1. API Group Inconsistency (docs/api-reference.md:5): The document header states team.posit.co/v1beta1 but examples use team.posit.co/v1beta1. Verify this matches the actual CRD apiVersion (core.posit.team/v1beta1 is used elsewhere).

2. Go Version (CONTRIBUTING.md:29): Go 1.25+ is listed but Go 1.25 doesn't exist yet (as of early 2025, latest stable is 1.23). Check go.mod for the actual required version.

3. Version References (docs/guides/upgrading.md): The version-specific migration section references v1.2.0, v1.1.0, v1.0.4, v1.0.0. Confirm these are accurate historical versions or planned releases.

4. Copyright Year (dist/chart/README.md:398): Uses 2023-2026. Consider 2023-present to avoid annual updates.

Suggestions

• The pre-commit workflow in CONTRIBUTING.md mentions just format but CLAUDE.md only references just test. Consider aligning these for consistency.
• In troubleshooting commands, consider noting that posit-team-system should be substituted with the user's actual operator namespace if customized.

Overall Assessment

This is a high-quality documentation PR that fills significant gaps. The guides are well-structured, use consistent formatting, and include practical examples. The architecture diagrams are particularly valuable for understanding the operator's design.

The items noted above are minor and don't block the PR - they're suggestions for improvement either in this PR or follow-up work.