posit-dev · ian-flores · Mar 9, 2026 · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing to Team Operator
 
-Welcome! We appreciate your interest in contributing to the Team Operator project. This guide will help you get started with development and understand our contribution workflow.
+This guide covers development setup and contribution workflow for the Team Operator project.
 
 ## Table of Contents
 
@@ -16,7 +16,7 @@ Welcome! We appreciate your interest in contributing to the Team Operator projec
 
 ## Project Overview
 
-Team Operator is a Kubernetes operator built with [Kubebuilder](https://book.kubebuilder.io/) that automates the deployment, configuration, and management of Posit Team products (Workbench, Connect, Package Manager, and Chronicle) within Kubernetes clusters.
+Team Operator is a Kubernetes operator built with [Kubebuilder](https://book.kubebuilder.io/) that automates deployment, configuration, and management of Posit Team products (Workbench, Connect, Package Manager, and Chronicle) within Kubernetes clusters.
 
 > **Note**: This repository is under active development and is not yet ready for production use.
 
@@ -149,13 +149,13 @@ just mtest
    git checkout -b your-feature-name
    ```
 
-2. Keep branch names descriptive and use hyphens (avoid slashes):
+2. Use descriptive branch names with hyphens (avoid slashes):
    - Good: `add-workbench-scaling`, `fix-database-connection`
    - Avoid: `feature/workbench`, `fix/db`
 
 ### PR Title Conventions (Required)
 
-We use [Conventional Commits](https://www.conventionalcommits.org/) and **squash merging**. Your PR title becomes the commit message, so it must follow this format:
+We use [Conventional Commits](https://www.conventionalcommits.org/) and **squash merging**. Your PR title becomes the commit message and must follow this format:
 
 ```
 <type>(<scope>): <description>
@@ -203,11 +203,11 @@ feat!: change API response format
    go vet ./...
    ```
 
-3. **Follow existing patterns** - New code should look like it belongs in the codebase.
+3. **Follow existing patterns.** New code should match the codebase.
 
-4. **Keep functions focused** - Each function should do one thing well.
+4. **Keep functions focused.** Each function should do one thing well.
 
-5. **Use descriptive names** - Names should reveal intent.
+5. **Use descriptive names.** Names should reveal intent.
 
 ### Adding New CRD Fields
 
@@ -323,33 +323,33 @@ go tool cover -func coverage.out
 
 Include the following in your PR description:
 
-1. **Summary** - What does this PR do?
-2. **Motivation** - Why is this change needed?
-3. **Testing** - How was this tested?
-4. **Breaking changes** - Does this introduce any breaking changes?
-5. **Related issues** - Link to any related GitHub issues
+1. **Summary:** What does this PR do?
+2. **Motivation:** Why is this change needed?
+3. **Testing:** How was this tested?
+4. **Breaking changes:** Does this introduce any breaking changes?
+5. **Related issues:** Link to any related GitHub issues
 
 ### CI Checks
 
 The following checks must pass:
 
-- **PR Title Check** - Title must follow conventional commit format (see above)
-- **Build** - The operator must compile successfully
-- **Unit tests** - All tests must pass
-- **Kustomize** - Kustomization must build without errors
-- **Helm lint** - Chart must pass linting
-- **Helm template** - Templates must render correctly
-- **No diff** - Generated files must be committed
+- **PR Title Check:** Title must follow conventional commit format (see above)
+- **Build:** The operator must compile successfully
+- **Unit tests:** All tests must pass
+- **Kustomize:** Kustomization must build without errors
+- **Helm lint:** Chart must pass linting
+- **Helm template:** Templates must render correctly
+- **No diff:** Generated files must be committed
 
 ### Merging
 
-This repository uses **squash and merge**. Your PR title becomes the final commit message on `main`. This is why the PR title format is enforced - semantic-release analyzes these commit messages to determine version bumps.
+This repository uses **squash and merge**. Your PR title becomes the final commit message on `main`. The PR title format is enforced because semantic-release analyzes commit messages to determine version bumps.
 
 ### Review Expectations
 
 - PRs require at least one approval before merging
-- Address all review comments or explain why you disagree
-- Keep PRs focused - smaller PRs are easier to review
+- Address all review comments or explain disagreements
+- Keep PRs focused. Smaller PRs are easier to review.
 - Respond to feedback promptly
 
 ## Code Review Guidelines
@@ -358,9 +358,9 @@ We follow specific guidelines for code review. For detailed review standards, se
 
 ### Core Principles
 
-- **Simplicity** - Prefer explicit over clever
-- **Maintainability** - Follow existing patterns in the codebase
-- **Security** - Extra scrutiny for credential handling, RBAC, and network operations
+- **Simplicity:** Prefer explicit over clever
+- **Maintainability:** Follow existing patterns in the codebase
+- **Security:** Extra scrutiny for credential handling, RBAC, and network operations
 
 ### Review Checklist by Area
 
@@ -419,12 +419,12 @@ Once installed, roborev will run after each `git commit` and submit a review for
 
 ## Getting Help
 
-If you have questions or need help:
+If you have questions:
 
-1. **Check existing documentation** - README.md, this guide, and inline code comments
-2. **Search existing issues** - Your question may have been answered before
-3. **Open an issue** - For bugs, feature requests, or questions
-4. **Contact Posit** - For production use inquiries, [contact Posit](https://posit.co/schedule-a-call/)
+1. **Check existing documentation:** README.md, this guide, and inline code comments
+2. **Search existing issues:** Your question may have been answered
+3. **Open an issue:** For bugs, feature requests, or questions
+4. **Contact Posit:** For production use inquiries, [contact Posit](https://posit.co/schedule-a-call/)
 
 ## Quick Reference
 

diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 > **Warning**
 > This repository is under active development and is not yet ready for production use. Please [contact Posit](https://posit.co/schedule-a-call/) before using this operator.
 
-A Kubernetes operator that manages the deployment and lifecycle of Posit Team products (Workbench, Connect, Package Manager, and Chronicle) within Kubernetes clusters.
+A Kubernetes operator that manages deployment and lifecycle of Posit Team products (Workbench, Connect, Package Manager, and Chronicle) within Kubernetes clusters.
 
 ## Table of Contents
 
@@ -22,7 +22,7 @@ A Kubernetes operator that manages the deployment and lifecycle of Posit Team pr
 
 ## Overview
 
-The Team Operator is a Kubernetes controller built using [Kubebuilder](https://book.kubebuilder.io/) that automates the deployment, configuration, and management of Posit Team products. It handles:
+The Team Operator is a Kubernetes controller built with [Kubebuilder](https://book.kubebuilder.io/) that automates deployment, configuration, and management of Posit Team products. It handles:
 
 - Multi-product Posit Team deployments through a single `Site` Custom Resource
 - Database provisioning and management for each product
@@ -59,7 +59,7 @@ spec:
 ```
 
 **Layout behavior:**
-- When Academy is hidden (default), the three core products (Workbench, Connect, Package Manager) are displayed with Workbench and Connect in the first row, and Package Manager centered in the second row
+- When Academy is hidden (default), the three core products (Workbench, Connect, Package Manager) display with Workbench and Connect in the first row, Package Manager centered in the second row
 - When Academy is shown, all four products display in a 2x2 grid
 
 **Static assets:**
@@ -131,16 +131,16 @@ just helm-uninstall  # Uninstall via Helm
 make go-test
 ```
 
-**Integration tests** — two workflows:
+**Integration tests** use two workflows:
 
-*One-shot (CI-style):* creates a cluster, runs all tests, and tears everything down.
+*One-shot (CI-style):* creates a cluster, runs all tests, tears everything down.
 
 ```bash
 make test-kind       # create → deploy → test → destroy
 make test-kind-full  # same, but forces a clean cluster first
 ```
 
-*Dev loop (recommended for iterative development):* keep the cluster running between test runs.
+*Dev loop (recommended for iterative development):* keeps the cluster running between test runs.
 
 ```bash
 # One-time setup: create cluster and deploy operator
@@ -220,7 +220,7 @@ Site CR (single source of truth)
             └── PostgreSQL schemas, credentials, migrations
 ```
 
-Each product has dedicated database schemas and isolated credentials. Workbench and Connect support off-host execution where user workloads run in separate Kubernetes Jobs. Chronicle collects telemetry via sidecars injected into product pods.
+Each product has dedicated database schemas and isolated credentials. Workbench and Connect support off-host execution with user workloads in separate Kubernetes Jobs. Chronicle collects telemetry via sidecars injected into product pods.
 
 For detailed architecture diagrams with component explanations, see the [Architecture Documentation](docs/architecture.md).
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,10 +1,10 @@
 # Team Operator
 
-The Team Operator is a Kubernetes operator that manages the deployment and configuration of Posit Team products within a Kubernetes cluster.
+The Team Operator manages deployment and configuration of Posit Team products in Kubernetes.
 
 ## Overview
 
-The Team Operator automates the deployment and lifecycle management of:
+The operator automates deployment and lifecycle management of:
 - **Posit Workbench** - Interactive development environment
 - **Posit Connect** - Publishing and sharing platform
 - **Posit Package Manager** - Package repository management
@@ -24,7 +24,7 @@ Site CRD (single source of truth)
     └── Keycloak configuration
 ```
 
-The Site controller watches for Site resources and reconciles product-specific Custom Resources for each enabled product.
+The Site controller watches Site resources and creates product-specific Custom Resources for enabled products.
 
 ### Overall System Architecture
 
@@ -286,14 +286,14 @@ The `Site` Custom Resource is the primary configuration point. It contains:
 
 ### Configuration Propagation
 
-Configuration flows from Site CRD to individual product CRDs:
+Configuration flows from Site CRD to product CRDs:
 
 1. User edits Site spec
 2. Site controller detects change
 3. Site controller updates product CRs
 4. Product controllers reconcile deployments
 
-See [Adding Config Options](../guides/adding-config-options.md) for details on extending configuration.
+See [Adding Config Options](../guides/adding-config-options.md) for extending configuration.
 
 ## Quick Start
 
@@ -322,8 +322,8 @@ Team Operator uses two namespaces:
 
 | Namespace | Purpose |
 |-----------|---------|
-| `posit-team-system` | Where the operator controller runs |
-| `posit-team` (or configured `watchNamespace`) | Where Site CRs and deployed products live |
+| `posit-team-system` | Operator controller runs here |
+| `posit-team` (or configured `watchNamespace`) | Site CRs and deployed products run here |
 
 ## Related Documentation
 

diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -1,6 +1,6 @@
 # Team Operator API Reference
 
-This document provides a comprehensive reference for the Custom Resource Definitions (CRDs) provided by the Team Operator.
+This document covers the Custom Resource Definitions (CRDs) the Team Operator provides.
 
 **API Group:** `team.posit.co/v1beta1`
 
@@ -26,7 +26,7 @@ This document provides a comprehensive reference for the Custom Resource Definit
 
 ## Site
 
-The Site CRD is the primary resource for managing a complete Posit Team deployment. It orchestrates all product components (Connect, Workbench, Package Manager, Chronicle) within a single site.
+The Site CRD is the primary resource for managing a complete Posit Team deployment. It orchestrates all product components (Connect, Workbench, Package Manager, Chronicle) in a single site.
 
 **Kind:** `Site`
 **Plural:** `sites`
@@ -36,16 +36,16 @@ The Site CRD is the primary resource for managing a complete Posit Team deployme
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `.spec.domain` | `string` | **Yes** | The core domain name associated with the Posit Team Site |
+| `.spec.domain` | `string` | **Yes** | The core domain name for the Posit Team Site |
 | `.spec.awsAccountId` | `string` | No | AWS Account ID used for EKS-to-IAM annotations |
 | `.spec.clusterDate` | `string` | No | Cluster date ID (YYYYmmdd) used for EKS-to-IAM annotations |
 | `.spec.workloadCompoundName` | `string` | No | Name for the workload |
 | `.spec.secretType` | `SiteSecretType` | No | **DEPRECATED** - Type of secret management to use |
 | `.spec.ingressClass` | `string` | No | Ingress class for creating ingress routes |
 | `.spec.ingressAnnotations` | `map[string]string` | No | Annotations applied to all ingress routes |
-| `.spec.imagePullSecrets` | `[]string` | No | Image pull secrets for all image pulls (must exist in namespace) |
-| `.spec.volumeSource` | [`VolumeSource`](#volumesource) | No | Definition of where volumes should be created from |
-| `.spec.sharedDirectory` | `string` | No | Name of directory mounted into Workbench and Connect at `/mnt/<sharedDirectory>` (no slashes) |
+| `.spec.imagePullSecrets` | `[]string` | No | Image pull secrets for all image pulls (secrets must exist in namespace) |
+| `.spec.volumeSource` | [`VolumeSource`](#volumesource) | No | Where volumes are created from |
+| `.spec.sharedDirectory` | `string` | No | Directory name mounted into Workbench and Connect at `/mnt/<sharedDirectory>` (no slashes) |
 | `.spec.volumeSubdirJobOff` | `bool` | No | Disables VolumeSubdir provisioning Kubernetes job |
 | `.spec.extraSiteServiceAccounts` | `[]ServiceAccountConfig` | No | Additional service accounts prefixed by `<siteName>-` |
 | `.spec.secret` | [`SecretConfig`](#secretconfig) | No | Secret management configuration for this Site |
@@ -57,7 +57,7 @@ The Site CRD is the primary resource for managing a complete Posit Team deployme
 | `.spec.logFormat` | `LogFormat` | No | Log output format |
 | `.spec.networkTrust` | `NetworkTrust` | No | Network trust level (0-100, default: 100) |
 | `.spec.packageManagerUrl` | `string` | No | Package Manager URL for Workbench (defaults to local Package Manager) |
-| `.spec.efsEnabled` | `bool` | No | Enable EFS for this site (allows workbench sessions to access EFS mount targets) |
+| `.spec.efsEnabled` | `bool` | No | Enable EFS for this site (workbench sessions can access EFS mount targets) |
 | `.spec.vpcCIDR` | `string` | No | VPC CIDR block for EFS network policies |
 | `.spec.enableFqdnHealthChecks` | `*bool` | No | Enable FQDN-based health check targets for Grafana Alloy (default: true) |
 
@@ -119,7 +119,7 @@ spec:
 
 ## Connect
 
-The Connect CRD manages standalone Posit Connect deployments. When using the Site CRD, Connect configuration is typically specified via `.spec.connect` rather than creating a separate Connect resource.
+The Connect CRD manages standalone Posit Connect deployments. When using the Site CRD, specify Connect configuration through `.spec.connect` instead of creating a separate Connect resource.
 
 **Kind:** `Connect`
 **Plural:** `connects`
@@ -203,7 +203,7 @@ spec:
 
 ## Workbench
 
-The Workbench CRD manages standalone Posit Workbench deployments. When using the Site CRD, Workbench configuration is typically specified via `.spec.workbench` rather than creating a separate Workbench resource.
+The Workbench CRD manages standalone Posit Workbench deployments. When using the Site CRD, specify Workbench configuration through `.spec.workbench` instead of creating a separate Workbench resource.
 
 **Kind:** `Workbench`
 **Plural:** `workbenches`
@@ -292,7 +292,7 @@ spec:
 
 ## PackageManager
 
-The PackageManager CRD manages standalone Posit Package Manager deployments. When using the Site CRD, Package Manager configuration is typically specified via `.spec.packageManager` rather than creating a separate PackageManager resource.
+The PackageManager CRD manages standalone Posit Package Manager deployments. When using the Site CRD, specify Package Manager configuration through `.spec.packageManager` instead of creating a separate PackageManager resource.
 
 **Kind:** `PackageManager`
 **Plural:** `packagemanagers`
@@ -581,7 +581,7 @@ Authentication configuration used by Connect and Workbench.
 
 ### SecretConfig
 
-Configuration for secret management.
+Secret management configuration.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -598,7 +598,7 @@ Configuration for secret management.
 
 ### VolumeSource
 
-Configuration for the source of persistent volumes.
+Source configuration for persistent volumes.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -649,7 +649,7 @@ Product license configuration.
 
 ### SessionConfig
 
-Configuration for session pods (Connect and Workbench).
+Session pod configuration (Connect and Workbench).
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -743,8 +743,8 @@ These types are used within the Site CRD for product configuration.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `.enabled` | `*bool` | Controls whether Connect is running (default: true). Setting to `false` suspends Connect: stops pods and removes ingress/service, but preserves PVC, database, and secrets. Re-enabling restores full service without data loss. See [Connect Configuration Guide](guides/connect-configuration.md#enablingdisabling-connect). |
-| `.teardown` | `*bool` | When `true` and `enabled` is `false`, permanently destroys all Connect resources including the database, secrets, and PVC. Re-enabling after teardown starts fresh with an empty database. Defaults to `false`. |
+| `.enabled` | `*bool` | Controls whether Connect runs (default: true). Setting to `false` suspends Connect: stops pods and removes ingress/service, but preserves PVC, database, and secrets. Re-enabling restores full service without data loss. See [Connect Configuration Guide](guides/connect-configuration.md#enablingdisabling-connect). |
+| `.teardown` | `*bool` | When `true` and `enabled` is `false`, destroys all Connect resources including database, secrets, and PVC. Re-enabling after teardown starts fresh with an empty database. Defaults to `false`. |
 | `.license` | `LicenseSpec` | License configuration |
 | `.volume` | `*VolumeSpec` | Data volume |
 | `.nodeSelector` | `map[string]string` | Node selector |