diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e5be2c28..328ffd04 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,323 +1,352 @@
+
+
+
+
+
+
` | `TestCreateCluster` |
+| Test files | `_test.go` | `service_test.go` |
+| Constructor functions | `New()` | `NewK3dManager()`, `NewClusterService()` |
+
+### Error Handling Conventions
-Example test structure:
```go
-func TestClusterCreate(t *testing.T) {
- tests := []struct {
- name string
- input ClusterConfig
- expected error
- }{
- {
- name: "valid cluster creation",
- input: ClusterConfig{
- Name: "test-cluster",
- Nodes: 3,
- },
- expected: nil,
- },
- // Add more test cases...
- }
-
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- err := CreateCluster(tt.input)
- assert.Equal(t, tt.expected, err)
- })
- }
+// ✅ CORRECT — wrap with context
+if err := someOperation(); err != nil {
+ return fmt.Errorf("creating cluster %s: %w", name, err)
+}
+
+// ✅ CORRECT — use structured error types for user-facing errors
+return errors.CreateCommandError("k3d", args, originalErr)
+
+// ❌ WRONG — discarding context
+if err := someOperation(); err != nil {
+ return err
}
```
-### Commit Guidelines
+### Logging and Output
+
+- **Never use `fmt.Println` in service/provider code** — all user-facing output must go through `internal/shared/ui`
+- **Verbose output**: Wrap detailed logs in verbose-mode checks
+- **No secrets in logs**: Never log credential values, tokens, or passwords — even in verbose mode
+
+---
-Follow conventional commit format:
+## Branch Naming Convention
+
+| Branch Type | Format | Example |
+|---|---|---|
+| Feature | `feature/` | `feature/add-cluster-pause-command` |
+| Bug fix | `fix/` | `fix/k3d-timeout-on-slow-machines` |
+| Documentation | `docs/` | `docs/add-telepresence-guide` |
+| Refactor | `refactor/` | `refactor/executor-interface-cleanup` |
+| Release | `release/v..` | `release/v1.2.0` |
+
+**Rules:**
+- Use lowercase only
+- Use hyphens as word separators (not underscores or spaces)
+- Keep descriptions short (2–5 words)
+- Branch off `main` for all new work
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/my-new-feature
+```
+
+---
+
+## Commit Message Format
+
+OpenFrame CLI uses the [Conventional Commits](https://www.conventionalcommits.org/) format:
```text
-[optional scope]:
+():
[optional body]
-[optional footer(s)]
+[optional footer]
```
-**Types:**
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation changes
-- `style:` Code style changes (formatting, etc.)
-- `refactor:` Code refactoring
-- `test:` Adding or updating tests
-- `chore:` Build process or auxiliary tool changes
+### Commit Types
-**Examples:**
-```bash
-git commit -m "feat(cluster): add support for custom node configurations"
-git commit -m "fix(bootstrap): resolve ArgoCD installation timeout"
-git commit -m "docs: update prerequisites and installation guide"
+| Type | When to Use |
+|---|---|
+| `feat` | A new feature or capability |
+| `fix` | A bug fix |
+| `docs` | Documentation changes only |
+| `style` | Formatting, missing semicolons, no logic change |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `test` | Adding or updating tests |
+| `chore` | Build process, dependency updates, tooling changes |
+| `perf` | Performance improvements |
+
+### Scope Examples
+
+```text
+feat(cluster): add pause/resume cluster commands
+fix(chart): resolve ArgoCD wait timeout on slow machines
+docs(bootstrap): update non-interactive flag documentation
+test(executor): add mock response for k3d list command
+refactor(shared): consolidate error display in ErrorHandler
+chore(deps): update client-go to v0.29.0
```
-### Pull Request Process
+### Commit Message Rules
-1. **Prepare Your PR**
-```bash
-# Ensure your branch is up to date
-git fetch upstream
-git rebase upstream/main
+- Subject line: 72 characters max, imperative mood ("add X", not "added X" or "adds X")
+- No period at the end of the subject line
+- Body: wrap at 72 characters; explain *what* and *why*, not *how*
-# Run all checks
-go fmt ./...
-goimports -w .
-golangci-lint run
-go test ./...
+---
+
+## Pull Request Process
+
+### Before Opening a PR
+
+Complete this checklist:
+
+- [ ] Code is formatted with `gofmt` and `goimports`
+- [ ] All linter rules pass: `golangci-lint run ./...`
+- [ ] All tests pass: `go test ./...`
+- [ ] New code has corresponding unit tests
+- [ ] Vulnerability check passes: `govulncheck ./...`
+- [ ] PR description explains *what* changed and *why*
+
+### PR Title
+
+Follow the same Conventional Commits format as commit messages:
+
+```text
+feat(cluster): add cluster pause/resume subcommands
+fix(chart): handle ArgoCD sync timeout gracefully
+docs(dev): improve Telepresence intercept documentation
```
-2. **Submit Your Pull Request**
-- Use a clear, descriptive title
-- Include a detailed description of changes
-- Reference any related issues
-- Add screenshots/logs for UI or behavioral changes
-- Ensure all CI checks pass
+### PR Description Template
-3. **PR Template**
```markdown
-## Description
-Brief description of the changes and their purpose.
+## Summary
+Brief description of what this PR does and why.
-## Type of Change
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
+## Changes
+- Added `openframe cluster pause` command
+- Added `openframe cluster resume` command
+- Updated ClusterService with pause/resume methods
+- Added unit tests for pause/resume operations
## Testing
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing completed
-
-## Checklist
-- [ ] My code follows the project's style guidelines
-- [ ] I have performed a self-review of my code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
+Describe how you tested these changes:
+- Unit tests: `go test ./internal/cluster/...`
+- Manual test: `./openframe cluster pause test-cluster`
+
+## Related
+Link to Slack discussion or related context (if applicable).
```
-## Code Review Process
+### Review Checklist
-### For Contributors
-- Respond promptly to review feedback
-- Address all comments and suggestions
-- Ask questions if feedback is unclear
-- Update documentation if your changes affect user-facing behavior
+When reviewing a PR, verify:
-### For Reviewers
-- Provide constructive, actionable feedback
-- Focus on code quality, maintainability, and correctness
-- Check that tests adequately cover new functionality
-- Verify documentation updates are included
+**Code Quality**
+- [ ] Logic is clear and follows existing patterns
+- [ ] No unnecessary complexity or over-engineering
+- [ ] Error messages are user-friendly and actionable
+- [ ] No hardcoded values that should be configurable
-## Testing
+**Architecture**
+- [ ] New external tools are abstracted behind interfaces
+- [ ] Dependencies are injected (not instantiated inline)
+- [ ] Commands delegate to services; services delegate to providers
+- [ ] Shared infrastructure is used (don't re-implement logging, prompts, errors)
-### Running Tests
-```bash
-# Run all tests
-go test ./...
+**Testing**
+- [ ] Unit tests cover the happy path and error cases
+- [ ] Mock executor is used correctly (no real tool calls in unit tests)
-# Run tests with coverage
-go test -race -coverprofile=coverage.out ./...
-go tool cover -html=coverage.out
+**Security**
+- [ ] No credentials or secrets in source code
+- [ ] All user inputs are validated
+- [ ] External commands use `exec.Command` with arg arrays (not shell strings)
+- [ ] Temporary files are cleaned up with `defer`
-# Run specific package tests
-go test ./internal/cluster/...
+**Documentation**
+- [ ] Exported functions and types have Go doc comments
+- [ ] New commands have `Short` and `Long` descriptions in the Cobra command
-# Run integration tests (requires Docker)
-go test -tags=integration ./...
-```
+---
-### Test Categories
-- **Unit Tests**: Test individual functions and components
-- **Integration Tests**: Test interactions with external tools (Docker, kubectl, etc.)
-- **End-to-End Tests**: Test complete workflows from CLI to cluster
-
-### Writing Good Tests
-- Test both happy path and error conditions
-- Use descriptive test names that explain what is being tested
-- Keep tests focused and atomic
-- Use test fixtures and helpers to reduce duplication
-
-## Documentation
-
-### Types of Documentation
-- **Code Comments**: Explain complex logic and public APIs
-- **README Updates**: Keep installation and usage instructions current
-- **Developer Docs**: Architecture, design decisions, and development guides
-- **User Guides**: Step-by-step tutorials and reference material
-
-### Documentation Guidelines
-- Write clear, concise instructions
-- Include code examples where helpful
-- Update docs when making user-facing changes
-- Use proper Markdown formatting
-
-## Release Process
-
-### Version Management
-We use semantic versioning (SemVer):
-- **MAJOR**: Breaking changes
-- **MINOR**: New features (backward compatible)
-- **PATCH**: Bug fixes (backward compatible)
-
-### Creating a Release
-1. Update version in `main.go`
-2. Update `CHANGELOG.md`
-3. Create and push version tag
-4. GitHub Actions handles the build and release
-
-## Issue Management
-
-### Reporting Issues
-When reporting bugs or requesting features:
-- Check existing issues first
-- Use issue templates when available
-- Provide detailed reproduction steps for bugs
-- Include system information and versions
-
-### Working on Issues
-- Comment on issues before starting work
-- Ask for clarification if requirements are unclear
-- Link your PR to the issue when ready
-
-## Community Guidelines
-
-### Communication Channels
-- **Primary Support**: [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
-- **Development Discussion**: GitHub PR comments and code reviews
-- **Feature Requests**: GitHub Issues
-
-### Code of Conduct
-- Be respectful and inclusive in all interactions
-- Focus on constructive feedback and solutions
-- Help newcomers get started
-- Follow the project's technical standards and conventions
+## Adding New Commands
-## Getting Help
+When adding a new command, follow this pattern:
+
+1. **Create the command file**: `cmd//.go`
+2. **Register in group file**: Add to `cmd//.go`'s `AddCommand()` call
+3. **Create service logic**: `internal//services/.go`
+4. **Define interface**: Add to `internal//utils/types/interfaces.go`
+5. **Add prerequisite checks**: Update `internal//prerequisites/checker.go` if needed
+6. **Write unit tests**: `internal//services/_test.go`
+7. **Update inline docs**: Exported functions and types must have doc comments
+
+---
-Need assistance? Here's how to get help:
+## Local Validation Before Submitting
-1. **Development Questions**: Ask in OpenMSP Slack #dev channel
-2. **Documentation Issues**: Create a GitHub issue with the "documentation" label
-3. **Bug Reports**: File a GitHub issue with reproduction steps
-4. **Feature Ideas**: Discuss in Slack first, then create GitHub issue
+Run this sequence before opening a PR:
-## External Dependencies
+```bash
+# Format code
+gofmt -w .
+goimports -w .
-### CLI Tools Integration
-This repository contains OpenFrame CLI code. The main OpenFrame application code is maintained separately:
+# Lint
+golangci-lint run ./...
+
+# Test
+go test ./...
+
+# Vulnerability check
+govulncheck ./...
+
+# Build check
+go build -o /tmp/openframe-test ./main.go
+```
-- **OpenFrame Main Repository**: [flamingo-stack/openframe-oss-tenant](https://github.com/flamingo-stack/openframe-oss-tenant)
-- **CLI Documentation**: [CLI Documentation](https://github.com/flamingo-stack/openframe-oss-tenant/tree/main/docs)
+---
+
+## Repository Structure
+
+```text
+openframe-cli/
+├── main.go # Binary entry point
+├── cmd/ # Cobra CLI commands
+│ ├── root.go # Root command wiring
+│ ├── bootstrap/bootstrap.go # openframe bootstrap
+│ ├── cluster/ # openframe cluster *
+│ ├── chart/ # openframe chart *
+│ └── dev/ # openframe dev *
+├── internal/ # Business logic (not exported)
+│ ├── bootstrap/ # Bootstrap service
+│ ├── cluster/ # Cluster service, models, providers
+│ ├── chart/ # Chart service, models, providers, UI
+│ ├── dev/ # Dev service, intercept, scaffold
+│ └── shared/ # Cross-cutting concerns
+│ ├── executor/ # Command execution abstraction
+│ ├── errors/ # Error types and handlers
+│ ├── ui/ # Prompts, tables, logo, progress
+│ └── config/ # TLS, credentials, system init
+└── tests/ # Test utilities and integration tests
+ ├── testutil/ # Mock executors, flag factories
+ ├── integration/ # End-to-end CLI integration tests
+ └── mocks/ # Mock implementations
+```
+
+---
+
+## Getting Help
-When contributing CLI-related changes, coordinate with the main repository team through Slack.
+Stuck on something? The best place to ask is the **OpenMSP Slack**:
-## Acknowledgments
+| Resource | Link |
+|---|---|
+| OpenMSP Community | [openmsp.ai](https://www.openmsp.ai/) |
+| Slack Invite | [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) |
+| OpenFrame Platform | [openframe.ai](https://openframe.ai) |
+| Flamingo | [flamingo.run](https://flamingo.run) |
-Thank you for contributing to OpenFrame CLI! Your efforts help make IT operations more accessible and cost-effective for MSPs worldwide.
+Discuss your contribution idea in Slack before starting large changes — this avoids duplicated effort and ensures alignment with the project's direction.
---
-**Questions?** Join our [OpenMSP Slack community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) - we're here to help!
\ No newline at end of file
+
diff --git a/README.md b/README.md
index dc599187..724a340d 100644
--- a/README.md
+++ b/README.md
@@ -12,197 +12,265 @@
# OpenFrame CLI
-OpenFrame CLI is a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows. It provides seamless cluster lifecycle management, chart installation with ArgoCD, and developer-friendly tools for service intercepts and scaffolding.
+**OpenFrame CLI** is a modern, interactive command-line tool written in Go that bootstraps and manages OpenFrame Kubernetes environments. It is the primary entry point for spinning up fully functional, production-grade [OpenFrame](https://openframe.ai) deployments on local or remote Kubernetes clusters — in minutes, not days.
-[](https://www.youtube.com/watch?v=bINdW0CQbvY)
+OpenFrame CLI automates the full lifecycle of an OpenFrame environment: cluster provisioning, GitOps installation via ArgoCD, interactive Helm values configuration, and developer tooling for Telepresence intercepts and Skaffold hot-reload workflows.
-## What is OpenFrame CLI?
+It is part of the broader [OpenFrame](https://openframe.ai) platform — the unified, AI-driven MSP operations suite built by [Flamingo](https://flamingo.run).
-OpenFrame CLI is part of the broader [OpenFrame](https://openframe.ai) ecosystem - an AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation. The CLI serves as the entry point for developers and operators to bootstrap, manage, and develop on OpenFrame environments.
+---
-## Key Features
+[](https://www.youtube.com/watch?v=a45pzxtg27k)
-### 🚀 Complete Environment Bootstrapping
-- **One-command setup**: Bootstrap entire OpenFrame environments with `openframe bootstrap`
-- **Multi-mode deployment**: Support for OSS tenant, SaaS tenant, and SaaS shared modes
-- **Automated cluster creation**: Creates K3D clusters with all necessary components
-- **ArgoCD integration**: Automatic chart installation and application management
+---
-### 🔧 Cluster Management
-- **Lifecycle operations**: Create, delete, list, and monitor Kubernetes clusters
-- **K3D integration**: Lightweight Kubernetes for development and testing
-- **Status monitoring**: Real-time cluster health and resource monitoring
-- **Easy cleanup**: Remove clusters and associated resources with simple commands
+## ✨ Features
-### 📦 Chart & Application Management
-- **Helm chart installation**: Streamlined chart deployment with dependency management
-- **ArgoCD applications**: GitOps-based application lifecycle management
-- **App-of-apps pattern**: Hierarchical application management for complex deployments
-- **Synchronization monitoring**: Track deployment progress with detailed logging
+| Feature | Description |
+|---|---|
+| **One-command bootstrap** | `openframe bootstrap` provisions a cluster and installs all charts end-to-end |
+| **Interactive wizard** | Guided Helm values configuration — branch, Docker registry, ingress, deployment mode |
+| **K3D cluster management** | Create, delete, list, status, and cleanup local K3D clusters |
+| **ArgoCD GitOps** | Installs ArgoCD and deploys app-of-apps patterns with health monitoring |
+| **Telepresence intercepts** | Route live Kubernetes traffic to your local machine for rapid iteration |
+| **Skaffold hot-reload** | Rebuild and sync containers on code change within a running cluster |
+| **Non-interactive / CI mode** | All commands support `--non-interactive` flags for CI/CD pipelines |
+| **Cross-platform** | Supports macOS, Linux, and Windows (WSL2) |
+| **Prerequisite auto-installer** | Automatically detects and guides installation of Docker, k3d, kubectl, Helm, and more |
-### 🛠 Development Tools
-- **Service intercepts**: Local development with Telepresence integration
-- **Scaffolding**: Generate boilerplate code and configurations
-- **Live debugging**: Debug services running in Kubernetes from your local environment
-- **Hot reload**: Rapid development cycles with instant feedback
+---
-## Architecture Overview
+## 🏗️ Architecture
```mermaid
graph TB
- subgraph "CLI Commands"
- Bootstrap[openframe bootstrap]
- Cluster[openframe cluster]
- Chart[openframe chart]
- Dev[openframe dev]
+ subgraph CLI["CLI Layer (cmd/)"]
+ Root["openframe (root)"]
+ BootstrapCmd["bootstrap"]
+ ClusterCmd["cluster"]
+ ChartCmd["chart"]
+ DevCmd["dev"]
end
-
- subgraph "Core Services"
- ClusterSvc[Cluster Management]
- ChartSvc[Chart Installation]
- DevSvc[Development Tools]
+
+ subgraph Services["Internal Services"]
+ BootstrapSvc["Bootstrap Service"]
+ ClusterSvc["Cluster Service"]
+ ChartSvc["Chart Service"]
+ DevSvc["Dev Services"]
end
-
- subgraph "External Tools"
- K3D[K3D Clusters]
- Helm[Helm Charts]
- ArgoCD[ArgoCD Apps]
- Telepresence[Service Intercepts]
+
+ subgraph Providers["External Tool Providers"]
+ K3D["K3D"]
+ Helm["Helm"]
+ ArgoCD["ArgoCD"]
+ Git["Git"]
+ Telepresence["Telepresence"]
+ Skaffold["Skaffold"]
end
-
- subgraph "Target Environment"
- K8s[Kubernetes]
- Apps[Applications]
- Services[Microservices]
+
+ subgraph Target["Deployed Environment"]
+ K8s["Kubernetes Cluster"]
+ Apps["ArgoCD Applications"]
+ Services2["OpenFrame Microservices"]
end
-
- Bootstrap --> ClusterSvc
- Bootstrap --> ChartSvc
- Cluster --> ClusterSvc
- Chart --> ChartSvc
- Dev --> DevSvc
-
+
+ Root --> BootstrapCmd
+ Root --> ClusterCmd
+ Root --> ChartCmd
+ Root --> DevCmd
+
+ BootstrapCmd --> BootstrapSvc
+ ClusterCmd --> ClusterSvc
+ ChartCmd --> ChartSvc
+ DevCmd --> DevSvc
+
+ BootstrapSvc --> ClusterSvc
+ BootstrapSvc --> ChartSvc
+
ClusterSvc --> K3D
ChartSvc --> Helm
ChartSvc --> ArgoCD
+ ChartSvc --> Git
DevSvc --> Telepresence
-
+ DevSvc --> Skaffold
+
K3D --> K8s
Helm --> Apps
ArgoCD --> Apps
- Telepresence --> Services
+ Apps --> Services2
```
-## Quick Start
+---
+
+## 🖥️ Hardware Requirements
+
+| Tier | RAM | CPU Cores | Disk Space |
+|---|---|---|---|
+| **Minimum** | 24 GB | 6 cores | 50 GB |
+| **Recommended** | 32 GB | 12 cores | 100 GB |
-Get OpenFrame CLI up and running in 5 minutes!
+> K3D runs Kubernetes nodes as Docker containers. Insufficient memory is the most common cause of failed bootstraps — ensure Docker has access to at least 16 GB RAM.
-### System Requirements
+---
-| Resource | Minimum | Recommended |
-|----------|---------|-------------|
-| **RAM** | 24GB | 32GB |
-| **CPU Cores** | 6 cores | 12 cores |
-| **Disk Space** | 50GB free | 100GB free |
+## 🚀 Quick Start
-### Prerequisites
+### Step 1 — Install the CLI
-Before installation, ensure you have:
-- [Docker](https://docs.docker.com/get-docker/) 20.10+
-- [kubectl](https://kubernetes.io/docs/tasks/tools/) 1.25+
-- [Helm](https://helm.sh/docs/intro/install/) 3.10+
-- [K3D](https://k3d.io/v5.4.6/#installation) 5.0+
+#### macOS (Apple Silicon)
-### Installation
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar xz
+chmod +x openframe
+sudo mv openframe /usr/local/bin/
+```
+
+#### macOS (Intel)
-Choose your platform and install OpenFrame CLI:
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz | tar xz
+chmod +x openframe
+sudo mv openframe /usr/local/bin/
+```
#### Linux (AMD64)
+
```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar xz
+chmod +x openframe
sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
```
-#### macOS (Apple Silicon)
+#### Linux (ARM64)
+
```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar -xz
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_arm64.tar.gz | tar xz
+chmod +x openframe
sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
```
-#### Windows (WSL2)
-1. Download: https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip
-2. Extract and move `openframe.exe` to a directory in your `PATH`
-3. Open WSL2 terminal and verify access
+#### Windows (AMD64)
-### Bootstrap Your Environment
+1. Download: [openframe-cli_windows_amd64.zip](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip)
+2. Extract the zip archive
+3. Move `openframe.exe` to a directory in your `PATH` (e.g., `C:\Windows\System32\` or a custom tools folder)
-Create a complete OpenFrame environment with a single command:
+> **Windows users**: Run all commands from a WSL2 terminal for the best experience.
-```bash
-# Verify installation
-openframe --version
+---
-# Bootstrap complete environment
+### Step 2 — Bootstrap Your Environment
+
+```bash
+# Interactive bootstrap (recommended for first-time users)
openframe bootstrap
+# Non-interactive (CI/CD)
+openframe bootstrap my-cluster --deployment-mode=oss-tenant --non-interactive
+```
+
+The `bootstrap` command will:
+
+1. Check and guide installation of any missing prerequisites (Docker, k3d, kubectl, Helm, Git, mkcert)
+2. Create a local K3D Kubernetes cluster
+3. Install ArgoCD via Helm
+4. Clone and deploy the app-of-apps GitOps chart
+5. Wait for all ArgoCD applications to become Healthy and Synced
+
+> Typical bootstrap time: **5–15 minutes** depending on network speed and hardware.
+
+---
+
+### Step 3 — Verify
+
+```bash
# Check cluster status
-openframe cluster status
+openframe cluster status my-openframe
+
+# List all managed clusters
+openframe cluster list
```
-The bootstrap process creates:
-- K3D Kubernetes cluster
-- ArgoCD for GitOps deployment
-- Traefik ingress controller
-- Core monitoring and logging components
+---
+
+[](https://www.youtube.com/watch?v=-_56_qYvMWk)
-## Core Commands
+---
+
+## 📦 Deployment Modes
+
+| Mode | Repository | Use Case |
+|---|---|---|
+| `oss-tenant` | `openframe-oss-tenant` | Default self-hosted OpenFrame deployment |
+| `saas-tenant` | `openframe-saas-tenant` | SaaS managed tenant deployment |
+| `saas-shared` | `openframe-saas-shared` | Shared SaaS infrastructure deployment |
+
+> For most operators getting started, `oss-tenant` is the recommended deployment mode.
+
+---
+
+## 🧰 CLI Command Reference
-| Command | Description | Example |
-|---------|-------------|---------|
-| `openframe bootstrap` | Complete environment setup | `openframe bootstrap my-cluster` |
-| `openframe cluster create` | Create Kubernetes cluster | `openframe cluster create --nodes 3` |
-| `openframe cluster delete` | Remove existing cluster | `openframe cluster delete my-cluster` |
-| `openframe cluster status` | Show cluster information | `openframe cluster status` |
-| `openframe chart install` | Install charts with ArgoCD | `openframe chart install` |
-| `openframe dev intercept` | Start service intercepts | `openframe dev intercept my-service` |
+| Command | Description |
+|---|---|
+| `openframe bootstrap [name]` | Full environment setup: cluster create + chart install |
+| `openframe cluster create [name]` | Create a K3D cluster |
+| `openframe cluster delete [name]` | Delete a cluster |
+| `openframe cluster list` | List all managed clusters |
+| `openframe cluster status [name]` | Show cluster health and ArgoCD app status |
+| `openframe cluster cleanup [name]` | Remove unused Docker images and resources |
+| `openframe chart install [name]` | Install ArgoCD + app-of-apps on a cluster |
+| `openframe dev intercept [service]` | Start a Telepresence intercept for local development |
+| `openframe dev skaffold [cluster]` | Run a Skaffold hot-reload workflow |
-## Technology Stack
+---
-OpenFrame CLI integrates with industry-standard tools:
+## 🔧 Technology Stack
+
+| Component | Technology |
+|---|---|
+| Language | Go |
+| CLI framework | [Cobra](https://github.com/spf13/cobra) |
+| Terminal UI | [pterm](https://github.com/pterm/pterm) |
+| Interactive prompts | [promptui](https://github.com/manifoldco/promptui) |
+| Kubernetes client | [client-go](https://pkg.go.dev/k8s.io/client-go) |
+| ArgoCD client | [argo-cd/v2](https://pkg.go.dev/github.com/argoproj/argo-cd/v2) |
+| YAML processing | [sigs.k8s.io/yaml](https://pkg.go.dev/sigs.k8s.io/yaml), [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) |
+| Testing | [testify](https://github.com/stretchr/testify) |
+| Cluster provider | K3D |
+| GitOps | ArgoCD + Helm app-of-apps |
-- **Kubernetes**: Container orchestration with K3D for development
-- **ArgoCD**: GitOps continuous deployment
-- **Helm**: Package management for Kubernetes
-- **Telepresence**: Local development with remote services
-- **Docker**: Container runtime and image management
-- **Cobra**: Modern CLI framework with rich help and completion
+---
-## Documentation
+## 📚 Documentation
-📚 See the [Documentation](./docs/README.md) for comprehensive guides including:
+Comprehensive documentation is available in the [`docs/`](./docs/README.md) directory:
-- **Getting Started**: Prerequisites, installation, and first steps
-- **Development**: Local setup, architecture, and contribution guidelines
-- **Reference**: Technical documentation, API specs, and configuration
-- **CLI Tools**: Links to external repositories and tools
+- **[Getting Started](./docs/README.md)** — Prerequisites, quick start, and first steps
+- **[Development Guides](./docs/README.md)** — Local setup, architecture, testing, contributing
+- **[Reference](./docs/README.md)** — Full architecture reference and component documentation
-## Community and Support
+---
-OpenFrame is built by the community for the community:
+## 🤝 Community & Support
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) - Primary support channel
-- **Website**: [https://flamingo.run](https://flamingo.run)
-- **OpenFrame Platform**: [https://openframe.ai](https://openframe.ai)
+> **Support happens in Slack, not GitHub Issues.**
-> **Note**: We don't use GitHub Issues or Discussions. All support and community interaction happens in the OpenMSP Slack community.
+| Resource | Link |
+|---|---|
+| OpenMSP Community | [openmsp.ai](https://www.openmsp.ai/) |
+| Slack Invite | [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) |
+| OpenFrame Platform | [openframe.ai](https://openframe.ai) |
+| Flamingo | [flamingo.run](https://flamingo.run) |
-## License
+---
-This project is licensed under the Flamingo AI Unified License v1.0 - see the [LICENSE.md](LICENSE.md) file for details.
+## 🤲 Contributing
+
+We welcome contributions! Please read our [Contributing Guidelines](./CONTRIBUTING.md) before opening a pull request.
---
+
\ No newline at end of file
+
diff --git a/SECURITY.md b/SECURITY.md
index c6999183..49b47610 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -81,7 +81,12 @@ Flamingo AI implements reasonable technical and organizational safeguards, but *
Use of Flamingo AI products is entirely at your own risk. Customers are solely responsible for compliance with applicable data protection laws when deploying Flamingo AI software or participating in OpenMSP.
-## 11. Contact Information
+## 11. Text Messaging Opt-In Data
+
+Text messaging originator opt-in data and consent will not be shared with any third parties, excluding aggregators and providers of the Text Message services.
+
+
+## 12. Contact Information
**Privacy Inquiries:** privacy@flamingo.so
**General Information:** info@flamingo.so
@@ -89,3 +94,4 @@ Use of Flamingo AI products is entirely at your own risk. Customers are solely r
---
*By using Flamingo AI products, you acknowledge and agree to this Privacy Policy.*
+
diff --git a/docs/README.md b/docs/README.md
index 5d0cad47..39bf59cb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,120 +1,154 @@
-# OpenFrame CLI Documentation
+# OpenFrame CLI — Documentation
-Welcome to the comprehensive documentation for OpenFrame CLI - a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows.
+Welcome to the OpenFrame CLI documentation. This index provides navigation to all available guides, references, and architecture documentation.
-## 📚 Table of Contents
-
-### Getting Started
+[](https://www.youtube.com/watch?v=awc-yAnkhIo)
-New to OpenFrame CLI? Start here to get up and running quickly:
-
-- [Introduction](./getting-started/introduction.md) - Overview of OpenFrame CLI and key concepts
-- [Prerequisites](./getting-started/prerequisites.md) - System requirements and dependency installation
-- [Quick Start](./getting-started/quick-start.md) - Get OpenFrame running in 5 minutes
-- [First Steps](./getting-started/first-steps.md) - Explore key features and workflows
+---
-### Development
+## 📚 Table of Contents
-Resources for developers working on or with OpenFrame CLI:
+- [Getting Started](#-getting-started)
+- [Development](#-development)
+- [Reference Architecture](#-reference-architecture)
+- [Diagrams](#-architecture-diagrams)
+- [Quick Links](#-quick-links)
-- [Development Overview](./development/README.md) - Developer documentation index
-- [Environment Setup](./development/setup/environment.md) - IDE configuration, tools, and development environment
-- [Local Development](./development/setup/local-development.md) - Clone, build, and run OpenFrame CLI locally
-- [Architecture Overview](./development/architecture/README.md) - System design and component relationships
+---
-### Reference
+## 🚀 Getting Started
-Technical reference documentation generated from source code analysis:
+Everything you need to install the CLI and bootstrap your first OpenFrame environment.
-- [Architecture Documentation](./architecture/overview.md) - Comprehensive system architecture and component design
+| Guide | Description |
+|---|---|
+| [Introduction](./getting-started/introduction.md) | What is OpenFrame CLI, key features, target audience, and architecture overview |
+| [Prerequisites](./getting-started/prerequisites.md) | Hardware requirements, required software, OS support, and binary downloads |
+| [Quick Start](./getting-started/quick-start.md) | Install the CLI and bootstrap a complete environment in under 5 minutes |
+| [First Steps](./getting-started/first-steps.md) | Explore your new cluster, set up local dev workflows, and learn the commands |
-### Diagrams
+### Quick Install
-Visual documentation to understand system architecture and workflows:
+**macOS (Apple Silicon)**
-- [Architecture Diagrams](./diagrams/architecture/README.md) - Mermaid diagrams showing system design, data flows, and component relationships
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar xz
+chmod +x openframe && sudo mv openframe /usr/local/bin/
+```
-### CLI Tools
+**macOS (Intel)**
-The OpenFrame Main code Repository is maintained in a separate repository:
-- **Repository**: [flamingo-stack/openframe-oss-tenant](https://github.com/flamingo-stack/openframe-oss-tenant)
-- **Documentation**: [CLI Documentation](https://github.com/flamingo-stack/openframe-oss-tenant/tree/main/docs)
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz | tar xz
+chmod +x openframe && sudo mv openframe /usr/local/bin/
+```
-**Note**: CLI tools are NOT located in this repository. Always refer to the external repository for installation and usage.
+**Linux (AMD64)**
-## 🚀 Quick Navigation
+```bash
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar xz
+chmod +x openframe && sudo mv openframe /usr/local/bin/
+```
-### For New Users
-1. Check [Prerequisites](./getting-started/prerequisites.md)
-2. Follow [Quick Start](./getting-started/quick-start.md)
-3. Explore [First Steps](./getting-started/first-steps.md)
+**Windows (AMD64)**
+Download [openframe-cli_windows_amd64.zip](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip), extract, and add `openframe.exe` to your `PATH`.
-### For Developers
-1. Set up [Development Environment](./development/setup/environment.md)
-2. Review [Architecture Documentation](./architecture/overview.md)
-3. Check [Contributing Guidelines](../CONTRIBUTING.md)
+---
-### For System Administrators
-1. Review [Prerequisites](./getting-started/prerequisites.md) for system requirements
-2. Follow [Bootstrap Guide](./getting-started/quick-start.md#step-3-bootstrap-your-first-environment)
-3. Explore cluster management commands in [First Steps](./getting-started/first-steps.md)
+## 🛠️ Development
+
+Guides for contributors and developers working on the OpenFrame CLI codebase.
+
+| Guide | Description |
+|---|---|
+| [Development Overview](./development/README.md) | Overview of the development workflow, technology stack, and repository structure |
+| [Environment Setup](./development/setup/environment.md) | IDE configuration, Go toolchain, recommended extensions, and Docker resources |
+| [Local Development](./development/setup/local-development.md) | Clone, build, run, debug, and iterate on the CLI locally |
+| [Architecture Overview](./development/architecture/README.md) | High-level architecture, component relationships, bootstrap flow, and design decisions |
+| [Testing Guide](./development/testing/README.md) | Test organization, running tests, writing unit and integration tests, mock executor |
+| [Security Best Practices](./development/security/README.md) | Credential management, TLS, secrets handling, and secure development guidelines |
+| [Contributing Guidelines](./development/contributing/guidelines.md) | Code style, branch naming, commit format, PR process, and review checklist |
+
+### Technology Stack
+
+| Component | Technology |
+|---|---|
+| Language | Go 1.21+ |
+| CLI framework | [Cobra](https://github.com/spf13/cobra) |
+| Terminal UI | [pterm](https://github.com/pterm/pterm) |
+| Interactive prompts | [promptui](https://github.com/manifoldco/promptui) |
+| Kubernetes client | [client-go](https://pkg.go.dev/k8s.io/client-go) |
+| ArgoCD client | [argo-cd/v2](https://pkg.go.dev/github.com/argoproj/argo-cd/v2) |
+| Testing | [testify](https://github.com/stretchr/testify) |
+| Cluster provider | K3D |
+| GitOps | ArgoCD + Helm app-of-apps |
-## 🎯 Key Features Covered
+---
-This documentation covers all major OpenFrame CLI capabilities:
+## 📖 Reference Architecture
-- **Complete Environment Bootstrapping**: One-command setup with `openframe bootstrap`
-- **Cluster Management**: Create, delete, and monitor K3D Kubernetes clusters
-- **Chart & Application Management**: Helm charts and ArgoCD GitOps workflows
-- **Development Tools**: Service intercepts, scaffolding, and local development workflows
-- **Multi-mode Deployment**: OSS tenant, SaaS tenant, and SaaS shared configurations
+Detailed technical reference generated from CodeWiki source analysis.
-## 📖 Quick Links
+| Document | Description |
+|---|---|
+| [Architecture Overview](./reference/architecture/overview.md) | Complete component documentation: CLI layer, internal services, providers, shared infrastructure, CLI commands, and dependency graph |
-- [Project README](../README.md) - Main project overview and installation
-- [Contributing](../CONTRIBUTING.md) - How to contribute to OpenFrame CLI
-- [License](../LICENSE.md) - Project license information
+### Deployment Modes
-## 🏗️ System Requirements
+| Mode | Repository | Use Case |
+|---|---|---|
+| `oss-tenant` | `openframe-oss-tenant` | Default self-hosted OpenFrame deployment |
+| `saas-tenant` | `openframe-saas-tenant` | SaaS managed tenant deployment |
+| `saas-shared` | `openframe-saas-shared` | Shared SaaS infrastructure deployment |
-Before using OpenFrame CLI, ensure your system meets these requirements:
+---
-| Resource | Minimum | Recommended |
-|----------|---------|-------------|
-| **RAM** | 24GB | 32GB |
-| **CPU Cores** | 6 cores | 12 cores |
-| **Disk Space** | 50GB free | 100GB free |
+## 🗺️ Architecture Diagrams
-## 🛠️ Core Dependencies
+Visual documentation of the CLI architecture and data flows. Diagrams are in [Mermaid](https://mermaid.js.org/) format.
-Required tools that must be installed:
-- [Docker](https://docs.docker.com/get-docker/) 20.10+
-- [kubectl](https://kubernetes.io/docs/tasks/tools/) 1.25+
-- [Helm](https://helm.sh/docs/intro/install/) 3.10+
-- [K3D](https://k3d.io/v5.4.6/#installation) 5.0+
+| Diagram | Description |
+|---|---|
+| [High-Level Architecture](./diagrams/architecture/high-level-architecture-diagram.mmd) | Top-level view of the CLI layer, services, providers, and target environment |
+| [Dependency Graph](./diagrams/architecture/dependency-graph.mmd) | How commands, services, providers, and shared infrastructure relate |
+| [Bootstrap Command Sequence](./diagrams/architecture/bootstrap-command-sequence.mmd) | Step-by-step sequence of the `openframe bootstrap` command |
+| [Chart Install Configuration Flow](./diagrams/architecture/chart-install-interactive-configuration-flow.mmd) | Interactive wizard flow for Helm values configuration |
+| [How Dependencies Are Used](./diagrams/architecture/how-dependencies-are-used.mmd) | Library dependency usage across CLI components |
-## 🌟 What Makes OpenFrame CLI Different
+---
-- **One-Command Bootstrap**: Complete environment setup with single command
-- **Developer-Friendly**: Interactive prompts, clear error messages, rich terminal UI
-- **GitOps Native**: Built-in ArgoCD integration for modern deployment practices
-- **Local Development**: Telepresence service intercepts for debugging
-- **Multi-Platform**: Linux, macOS, and Windows (WSL2) support
-- **Open Source**: Complete transparency and community-driven development
+## ⚡ CLI Command Reference
-## 🤝 Community and Support
+| Command | Description |
+|---|---|
+| `openframe bootstrap [name]` | Full environment setup: cluster create + chart install |
+| `openframe cluster create [name]` | Create a K3D cluster |
+| `openframe cluster delete [name]` | Delete a cluster |
+| `openframe cluster list` | List all managed clusters |
+| `openframe cluster status [name]` | Show cluster health and ArgoCD app status |
+| `openframe cluster cleanup [name]` | Remove unused Docker images and resources |
+| `openframe chart install [name]` | Install ArgoCD + app-of-apps on a cluster |
+| `openframe dev intercept [service]` | Start a Telepresence intercept for local development |
+| `openframe dev skaffold [cluster]` | Run a Skaffold hot-reload workflow |
-Need help or want to contribute?
+---
-- **Primary Support**: [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
-- **Website**: [https://flamingo.run](https://flamingo.run)
-- **OpenFrame Platform**: [https://openframe.ai](https://openframe.ai)
+## 🔗 Quick Links
-> **Note**: We don't monitor GitHub Issues for support. All community support and discussion happens in our Slack workspace.
+| Resource | Link |
+|---|---|
+| [Project README](../README.md) | Main project overview and quick start |
+| [Contributing Guide](../CONTRIBUTING.md) | How to contribute to OpenFrame CLI |
+| [OpenMSP Community](https://www.openmsp.ai/) | Join the Slack community for support |
+| [Slack Invite](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) | Direct invite link |
+| [OpenFrame Platform](https://openframe.ai) | The full OpenFrame platform |
+| [Flamingo](https://flamingo.run) | Built by Flamingo |
-## 📝 Documentation Maintenance
+---
-This documentation is automatically generated and maintained by the OpenFrame development team. If you find errors or have suggestions for improvement, please reach out in the OpenMSP Slack community.
+> **Support happens in Slack, not GitHub Issues.**
+> All questions, bug reports, and feature requests are handled in the [OpenMSP Slack community](https://www.openmsp.ai/).
---
-*Documentation generated by [OpenFrame Doc Orchestrator](https://github.com/flamingo-stack/openframe-oss-tenant)*
\ No newline at end of file
+
+*Documentation generated by [OpenFrame Doc Orchestrator](https://github.com/flamingo-stack/openframe-oss-tenant)*
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
deleted file mode 100644
index 87ceae9f..00000000
--- a/docs/architecture/overview.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# openframe-cli Module Documentation
-
-# OpenFrame CLI Architecture Documentation
-
-OpenFrame CLI is a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows, providing seamless cluster lifecycle management, chart installation with ArgoCD, and developer-friendly tools for service intercepts and scaffolding.
-
-## Architecture
-
-### High-Level System Design
-
-```mermaid
-graph TB
- subgraph "CLI Layer"
- Root[Root Command]
- Bootstrap[Bootstrap Command]
- Cluster[Cluster Commands]
- Chart[Chart Commands]
- Dev[Dev Commands]
- end
-
- subgraph "Service Layer"
- ClusterSvc[Cluster Service]
- ChartSvc[Chart Service]
- InterceptSvc[Intercept Service]
- ScaffoldSvc[Scaffold Service]
- end
-
- subgraph "Provider Layer"
- K3D[K3D Provider]
- Helm[Helm Provider]
- ArgoCD[ArgoCD Provider]
- Telepresence[Telepresence Provider]
- Kubectl[Kubectl Provider]
- end
-
- subgraph "External Systems"
- Docker[Docker]
- K8s[Kubernetes]
- Git[Git Repositories]
- Registry[Container Registry]
- end
-
- Root --> Bootstrap
- Root --> Cluster
- Root --> Chart
- Root --> Dev
-
- Bootstrap --> ClusterSvc
- Bootstrap --> ChartSvc
- Cluster --> ClusterSvc
- Chart --> ChartSvc
- Dev --> InterceptSvc
- Dev --> ScaffoldSvc
-
- ClusterSvc --> K3D
- ChartSvc --> Helm
- ChartSvc --> ArgoCD
- InterceptSvc --> Telepresence
- InterceptSvc --> Kubectl
- ScaffoldSvc --> Kubectl
-
- K3D --> Docker
- Helm --> K8s
- ArgoCD --> K8s
- ArgoCD --> Git
- Telepresence --> K8s
- Kubectl --> K8s
-```
-
-## Core Components
-
-| Component | Package | Responsibility |
-|-----------|---------|---------------|
-| **CLI Commands** | `cmd/` | Command definitions and argument parsing using Cobra |
-| **Cluster Service** | `internal/cluster/` | Kubernetes cluster lifecycle management (K3D) |
-| **Chart Service** | `internal/chart/` | Helm chart and ArgoCD application management |
-| **Dev Tools** | `internal/dev/` | Development workflows (Telepresence, Skaffold) |
-| **Bootstrap Service** | `internal/bootstrap/` | Complete environment setup orchestration |
-| **K3D Provider** | `internal/cluster/providers/k3d/` | K3D cluster operations and configuration |
-| **Helm Provider** | `internal/chart/providers/helm/` | Helm chart installation and management |
-| **ArgoCD Provider** | `internal/chart/providers/argocd/` | ArgoCD application lifecycle and monitoring |
-| **Telepresence Provider** | `internal/dev/providers/telepresence/` | Traffic interception for local development |
-| **Shared Utilities** | `internal/shared/` | Common functionality (UI, config, errors, execution) |
-| **Prerequisites** | `internal/*/prerequisites/` | Tool installation and validation |
-
-## Component Relationships
-
-### Dependency Flow Between Modules
-
-```mermaid
-graph TD
- subgraph "Command Layer"
- RootCmd[Root Command]
- BootstrapCmd[Bootstrap Command]
- ClusterCmd[Cluster Commands]
- ChartCmd[Chart Commands]
- DevCmd[Dev Commands]
- end
-
- subgraph "Service Orchestration"
- BootstrapSvc[Bootstrap Service]
- end
-
- subgraph "Domain Services"
- ClusterSvc[Cluster Service]
- ChartSvc[Chart Service]
- InterceptSvc[Intercept Service]
- ScaffoldSvc[Scaffold Service]
- end
-
- subgraph "Provider Implementations"
- K3DMgr[K3D Manager]
- HelmMgr[Helm Manager]
- ArgoCDMgr[ArgoCD Manager]
- TelepresenceProv[Telepresence Provider]
- KubectlProv[Kubectl Provider]
- GitRepo[Git Repository]
- end
-
- subgraph "Shared Infrastructure"
- Executor[Command Executor]
- UI[UI Components]
- Config[Configuration]
- Prerequisites[Prerequisites]
- end
-
- RootCmd --> BootstrapCmd
- RootCmd --> ClusterCmd
- RootCmd --> ChartCmd
- RootCmd --> DevCmd
-
- BootstrapCmd --> BootstrapSvc
- ClusterCmd --> ClusterSvc
- ChartCmd --> ChartSvc
- DevCmd --> InterceptSvc
- DevCmd --> ScaffoldSvc
-
- BootstrapSvc --> ClusterSvc
- BootstrapSvc --> ChartSvc
-
- ClusterSvc --> K3DMgr
- ChartSvc --> HelmMgr
- ChartSvc --> ArgoCDMgr
- ChartSvc --> GitRepo
- InterceptSvc --> TelepresenceProv
- InterceptSvc --> KubectlProv
- ScaffoldSvc --> KubectlProv
-
- K3DMgr --> Executor
- HelmMgr --> Executor
- ArgoCDMgr --> Executor
- TelepresenceProv --> Executor
- KubectlProv --> Executor
- GitRepo --> Executor
-
- ClusterSvc --> UI
- ChartSvc --> UI
- InterceptSvc --> UI
- ScaffoldSvc --> UI
-
- ClusterSvc --> Config
- ChartSvc --> Config
-
- ClusterSvc --> Prerequisites
- ChartSvc --> Prerequisites
- DevCmd --> Prerequisites
-```
-
-## Data Flow
-
-### Complete Bootstrap Workflow
-
-```mermaid
-sequenceDiagram
- participant User
- participant Bootstrap as Bootstrap Service
- participant Cluster as Cluster Service
- participant K3D as K3D Provider
- participant Chart as Chart Service
- participant Helm as Helm Provider
- participant ArgoCD as ArgoCD Provider
- participant K8s as Kubernetes API
-
- User->>Bootstrap: openframe bootstrap
- Bootstrap->>Bootstrap: Check prerequisites
- Bootstrap->>Cluster: Create cluster
- Cluster->>K3D: Create K3D cluster
- K3D->>K8s: Initialize cluster
- K8s-->>K3D: Cluster ready
- K3D-->>Cluster: Cluster config
- Cluster-->>Bootstrap: rest.Config
-
- Bootstrap->>Chart: Install charts
- Chart->>Helm: Install ArgoCD
- Helm->>K8s: Deploy ArgoCD
- K8s-->>Helm: ArgoCD running
- Helm-->>Chart: Installation complete
-
- Chart->>ArgoCD: Install app-of-apps
- ArgoCD->>K8s: Create Application CRDs
- K8s-->>ArgoCD: Applications created
- ArgoCD->>ArgoCD: Sync applications
- ArgoCD-->>Chart: Applications synced
- Chart-->>Bootstrap: Charts installed
- Bootstrap-->>User: Environment ready
-```
-
-### Development Intercept Workflow
-
-```mermaid
-sequenceDiagram
- participant Dev as Developer
- participant Intercept as Intercept Service
- participant Kubectl as Kubectl Provider
- participant Telepresence as Telepresence Provider
- participant K8s as Kubernetes
- participant Local as Local Development
-
- Dev->>Intercept: openframe dev intercept
- Intercept->>Kubectl: Get services
- Kubectl->>K8s: List services
- K8s-->>Kubectl: Service list
- Kubectl-->>Intercept: Available services
- Intercept->>Dev: Select service/port
- Dev->>Intercept: Service selection
-
- Intercept->>Telepresence: Setup intercept
- Telepresence->>K8s: Create intercept
- K8s->>Telepresence: Traffic routing active
- Telepresence->>Local: Forward traffic
- Local->>Dev: Local debugging
-
- Note over Dev,Local: Development session active
-
- Dev->>Intercept: Stop intercept (Ctrl+C)
- Intercept->>Telepresence: Cleanup intercept
- Telepresence->>K8s: Remove routing
- K8s-->>Telepresence: Cleanup complete
- Telepresence-->>Intercept: Disconnected
- Intercept-->>Dev: Session ended
-```
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `main.go` | Application entry point and version configuration |
-| `cmd/root.go` | Root command definition and global flag management |
-| `cmd/bootstrap/bootstrap.go` | Complete environment bootstrap command |
-| `internal/cluster/service.go` | Core cluster management business logic |
-| `internal/cluster/providers/k3d/manager.go` | K3D cluster provider implementation |
-| `internal/chart/services/chart_service.go` | Chart installation orchestration |
-| `internal/chart/providers/helm/manager.go` | Helm chart deployment logic |
-| `internal/chart/providers/argocd/applications.go` | ArgoCD application management |
-| `internal/dev/services/intercept/service.go` | Telepresence intercept workflow |
-| `internal/shared/executor/executor.go` | Command execution abstraction with WSL support |
-| `internal/shared/ui/logo.go` | Terminal UI and branding components |
-
-## Dependencies
-
-The project integrates with several external tools and libraries:
-
-### Core Kubernetes Libraries
-- **client-go**: Native Kubernetes API access for cluster operations
-- **apiextensions**: CRD management for ArgoCD applications
-- **kubectl**: Command-line cluster interaction fallback
-
-### CLI Framework
-- **cobra**: Command structure, argument parsing, and help generation
-- **pterm**: Rich terminal UI components, spinners, and progress bars
-- **promptui**: Interactive prompts and user input validation
-
-### External Tool Integration
-- **K3D**: Lightweight Kubernetes cluster management
-- **Helm**: Chart packaging and deployment via command execution
-- **ArgoCD**: GitOps application lifecycle through API and CLI
-- **Telepresence**: Service mesh traffic interception
-- **Docker**: Container runtime for K3D clusters
-
-### Configuration and State
-- **YAML**: Configuration file parsing for Helm values and cluster specs
-- **JSON**: Structured data exchange with Kubernetes APIs
-- **Home directory**: User configuration and certificate storage
-
-## CLI Commands
-
-### Core Commands
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `openframe bootstrap` | Complete environment setup (cluster + charts) | `openframe bootstrap my-cluster` |
-| `openframe cluster create` | Create new Kubernetes cluster | `openframe cluster create --nodes 3` |
-| `openframe cluster delete` | Remove existing cluster | `openframe cluster delete my-cluster` |
-| `openframe cluster list` | Show all available clusters | `openframe cluster list` |
-| `openframe cluster status` | Detailed cluster information | `openframe cluster status my-cluster` |
-| `openframe chart install` | Install ArgoCD and applications | `openframe chart install` |
-| `openframe dev intercept` | Start Telepresence traffic intercept | `openframe dev intercept my-service --port 8080` |
-| `openframe dev skaffold` | Development workflow with hot reload | `openframe dev skaffold my-cluster` |
-
-### Command Options
-
-**Global Flags:**
-- `--verbose, -v`: Enable detailed logging and progress information
-- `--dry-run`: Show planned operations without execution
-- `--force, -f`: Skip confirmation prompts for automation
-
-**Bootstrap Flags:**
-- `--deployment-mode`: Pre-select deployment type (oss-tenant, saas-tenant, saas-shared)
-- `--non-interactive`: Use existing configuration without prompts
-
-**Cluster Creation Flags:**
-- `--nodes, -n`: Number of worker nodes (default: 3)
-- `--type, -t`: Cluster type (k3d, gke)
-- `--version`: Kubernetes version
-- `--skip-wizard`: Use defaults without interactive configuration
-
-**Development Flags:**
-- `--port`: Local port for traffic forwarding
-- `--namespace`: Kubernetes namespace for operations
-- `--mount`: Mount remote volumes locally
-- `--env-file`: Load environment variables from file
diff --git a/docs/development/README.md b/docs/development/README.md
index 8ef86fdf..95de2cf9 100644
--- a/docs/development/README.md
+++ b/docs/development/README.md
@@ -1,180 +1,107 @@
# Development Documentation
-This section contains comprehensive guides for developing with and contributing to OpenFrame CLI. Whether you're setting up a development environment, understanding the architecture, or contributing code, these guides will help you get started.
+Welcome to the OpenFrame CLI development guide. This section covers everything you need to contribute to, build, test, and extend the OpenFrame CLI codebase.
-## 🏗️ Architecture & Design
-
-Understanding how OpenFrame CLI is structured and how its components interact:
-
-- **[Architecture Overview](architecture/README.md)** - High-level system design, component relationships, and data flows
-
-## 🛠️ Development Setup
-
-Get your development environment ready:
-
-- **[Environment Setup](setup/environment.md)** - IDE configuration, tools, and development dependencies
-- **[Local Development](setup/local-development.md)** - Clone, build, run, and debug OpenFrame CLI locally
-
-## 🔒 Security
-
-Security best practices and guidelines:
+---
-- **[Security Guidelines](security/README.md)** - Authentication patterns, data protection, and vulnerability prevention
+## Overview
-## 🧪 Testing
+OpenFrame CLI is written in **Go** and uses [Cobra](https://github.com/spf13/cobra) for command routing. The codebase follows a layered architecture: CLI commands delegate to internal services, which use provider abstractions over external tools (K3D, Helm, ArgoCD, Git, Telepresence, Skaffold).
-Comprehensive testing approaches:
+```mermaid
+graph LR
+ A["cmd/ (CLI Commands)"] --> B["internal/ (Services)"]
+ B --> C["providers/ (External Tools)"]
+ B --> D["internal/shared/ (Infrastructure)"]
+ C --> E["K3D / Helm / ArgoCD / Git"]
+ D --> F["Executor / UI / Errors / Config"]
+```
-- **[Testing Guide](testing/README.md)** - Test structure, running tests, writing new tests, and coverage requirements
+---
-## 🤝 Contributing
+## Documentation Index
-Guidelines for contributing to the project:
+| Guide | Description |
+|---|---|
+| [Environment Setup](setup/environment.md) | IDE configuration, development tools, editor extensions |
+| [Local Development](setup/local-development.md) | Clone, build, run, and debug the CLI locally |
+| [Architecture Overview](architecture/README.md) | High-level architecture, component relationships, data flows |
+| [Security Best Practices](security/README.md) | Auth patterns, secrets management, security guidelines |
+| [Testing Guide](testing/README.md) | Test structure, running tests, writing new tests |
+| [Contributing Guidelines](contributing/guidelines.md) | Code style, branch naming, PR process, commit conventions |
-- **[Contributing Guidelines](contributing/guidelines.md)** - Code standards, review process, and submission guidelines
+---
## Quick Navigation
-### New Contributors
-If you're new to OpenFrame CLI development, start here:
-1. [Architecture Overview](architecture/README.md) - Understand the system
-2. [Environment Setup](setup/environment.md) - Configure your tools
-3. [Local Development](setup/local-development.md) - Get the code running
-4. [Contributing Guidelines](contributing/guidelines.md) - Learn the process
-
-### Experienced Developers
-Jump to specific areas:
-- **Architecture**: Deep dive into design patterns and component interactions
-- **Security**: Review security models and best practices
-- **Testing**: Understand test patterns and coverage expectations
+### I want to…
-### Operations & DevOps
-Focus on deployment and operational aspects:
-- **Architecture**: Service dependencies and operational considerations
-- **Security**: Production security requirements and configurations
-- **Testing**: Integration and end-to-end testing strategies
+**Set up my development environment**
+→ Start with [Environment Setup](setup/environment.md), then follow [Local Development](setup/local-development.md)
-## Development Workflow Overview
+**Understand how the code is organized**
+→ Read the [Architecture Overview](architecture/README.md)
-```mermaid
-flowchart TD
- A[Fork Repository] --> B[Setup Dev Environment]
- B --> C[Create Feature Branch]
- C --> D[Write Code & Tests]
- D --> E[Run Local Tests]
- E --> F{Tests Pass?}
- F -->|No| D
- F -->|Yes| G[Commit Changes]
- G --> H[Push to Fork]
- H --> I[Create Pull Request]
- I --> J[Code Review]
- J --> K{Review Approved?}
- K -->|No| D
- K -->|Yes| L[Merge to Main]
- L --> M[CI/CD Pipeline]
- M --> N[Deploy & Test]
-```
+**Run or write tests**
+→ Go to the [Testing Guide](testing/README.md)
-## Key Technologies
+**Submit a contribution**
+→ Review the [Contributing Guidelines](contributing/guidelines.md)
-OpenFrame CLI is built with:
+**Understand security considerations**
+→ Read [Security Best Practices](security/README.md)
-| Technology | Purpose | Version |
-|------------|---------|---------|
-| **Go** | Primary language | 1.24.6+ |
-| **Cobra** | CLI framework | v1.8.1+ |
-| **Kubernetes** | Container orchestration | v1.31.2+ |
-| **K3D** | Local Kubernetes clusters | v5.0+ |
-| **Helm** | Package management | v3.10+ |
-| **ArgoCD** | GitOps deployments | v2.14+ |
-| **Telepresence** | Service intercepts | v2.10+ |
+---
-## Project Structure
+## Repository Structure at a Glance
```text
openframe-cli/
-├── cmd/ # CLI command definitions
-│ ├── bootstrap/ # Bootstrap command
-│ ├── cluster/ # Cluster management commands
-│ ├── chart/ # Chart installation commands
-│ ├── dev/ # Development workflow commands
-│ └── root.go # Root command setup
-├── internal/ # Internal packages
-│ ├── bootstrap/ # Bootstrap orchestration
-│ ├── cluster/ # Cluster lifecycle management
-│ ├── chart/ # Chart and ArgoCD integration
-│ ├── dev/ # Development tools
-│ └── shared/ # Common utilities
-├── tests/ # Test suites
-│ ├── integration/ # Integration tests
-│ ├── mocks/ # Test mocks
-│ └── testutil/ # Test utilities
-├── docs/ # Documentation
-├── examples/ # Usage examples
-├── scripts/ # Build and utility scripts
-├── go.mod # Go module definition
-├── go.sum # Go dependency checksums
-└── main.go # Application entry point
+├── main.go # Binary entry point
+├── cmd/ # Cobra CLI commands
+│ ├── root.go # Root command wiring
+│ ├── bootstrap/bootstrap.go # openframe bootstrap
+│ ├── cluster/ # openframe cluster *
+│ ├── chart/ # openframe chart *
+│ └── dev/ # openframe dev *
+├── internal/ # Business logic (not exported)
+│ ├── bootstrap/ # Bootstrap service
+│ ├── cluster/ # Cluster service, models, providers
+│ ├── chart/ # Chart service, models, providers, UI
+│ ├── dev/ # Dev service, intercept, scaffold
+│ └── shared/ # Cross-cutting concerns
+│ ├── executor/ # Command execution abstraction
+│ ├── errors/ # Error types and handlers
+│ ├── ui/ # Prompts, tables, logo, progress
+│ ├── config/ # TLS, credentials, system init
+│ ├── files/ # File cleanup utilities
+│ └── flags/ # Global flag management
+└── tests/ # Test utilities and integration tests
+ ├── testutil/ # Mock executors, flag factories
+ ├── integration/ # End-to-end CLI integration tests
+ └── mocks/ # Mock implementations
```
-## Development Principles
-
-### Code Quality
-- **Clean Architecture**: Clear separation of concerns with layered design
-- **Testability**: All components designed for easy testing and mocking
-- **Error Handling**: Comprehensive error handling with user-friendly messages
-- **Documentation**: Code is self-documenting with clear comments
-
-### User Experience
-- **Interactive Design**: Wizard-style interfaces for complex operations
-- **Clear Feedback**: Progress indicators and status messages
-- **Error Recovery**: Helpful error messages with suggested solutions
-- **Consistency**: Uniform command patterns and flag usage
-
-### Operational Excellence
-- **Observability**: Comprehensive logging and monitoring capabilities
-- **Reliability**: Robust error handling and recovery mechanisms
-- **Performance**: Efficient resource usage and fast execution
-- **Security**: Secure defaults and best practices
-
-## Getting Started
-
-### Prerequisites
-Before diving into development, ensure you have:
-- Go 1.24.6 or later installed
-- Docker and Kubernetes tools (kubectl, helm, k3d)
-- Git and a code editor/IDE
-- Basic familiarity with Kubernetes concepts
-
-### Quick Start
-1. **Read the [Architecture Overview](architecture/README.md)** to understand the system
-2. **Follow the [Environment Setup](setup/environment.md)** guide
-3. **Complete the [Local Development](setup/local-development.md)** setup
-4. **Review [Contributing Guidelines](contributing/guidelines.md)** before making changes
-
-## Community & Support
-
-### Getting Help
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) for development questions
-- **Documentation**: Browse these guides for detailed information
-- **Code Reviews**: Learn from existing pull requests and code reviews
-
-### Contributing
-We welcome contributions! Here's how to get involved:
-1. **Start Small**: Begin with bug fixes or documentation improvements
-2. **Discuss Large Changes**: Use Slack to discuss major features or architectural changes
-3. **Follow Guidelines**: Adhere to coding standards and review processes
-4. **Be Patient**: Maintain a collaborative and respectful approach
-
-### Code of Conduct
-- Be respectful and inclusive in all interactions
-- Focus on constructive feedback and learning
-- Help others learn and grow in the community
-- Follow the project's established patterns and conventions
+---
+
+## Technology Stack
+
+| Component | Technology |
+|---|---|
+| Language | Go |
+| CLI framework | [Cobra](https://github.com/spf13/cobra) |
+| Terminal UI | [pterm](https://github.com/pterm/pterm) |
+| Interactive prompts | [promptui](https://github.com/manifoldco/promptui) |
+| Kubernetes client | [client-go](https://pkg.go.dev/k8s.io/client-go) |
+| ArgoCD client | [argo-cd/v2](https://pkg.go.dev/github.com/argoproj/argo-cd/v2) |
+| YAML processing | [sigs.k8s.io/yaml](https://pkg.go.dev/sigs.k8s.io/yaml), [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) |
+| Testing | [testify](https://github.com/stretchr/testify) |
+| Cluster provider | K3D (via CLI) |
+| GitOps | ArgoCD + Helm app-of-apps |
---
-Ready to start developing? Choose your path:
-- **New to the project**: Start with [Architecture Overview](architecture/README.md)
-- **Ready to code**: Jump to [Local Development](setup/local-development.md)
-- **Want to contribute**: Review [Contributing Guidelines](contributing/guidelines.md)
\ No newline at end of file
+## Getting Help
+
+- **OpenMSP Slack**: [openmsp.ai](https://www.openmsp.ai/) — primary support channel
+- **Join Slack**: [Slack invite link](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
diff --git a/docs/development/architecture/README.md b/docs/development/architecture/README.md
index c42f299d..fd643b9d 100644
--- a/docs/development/architecture/README.md
+++ b/docs/development/architecture/README.md
@@ -1,574 +1,278 @@
# Architecture Overview
-OpenFrame CLI is built with a clean, layered architecture that separates concerns and provides extensibility. This guide provides a comprehensive overview of the system design, component relationships, and key architectural decisions.
+OpenFrame CLI is a Go-based command-line tool built with a strict layered architecture. Commands at the top delegate to internal services, which use provider abstractions over external tools. All cross-cutting concerns (command execution, error handling, UI, configuration) live in a shared infrastructure layer.
-## High-Level Architecture
+> For the full architecture reference, see [./reference/architecture/overview.md](./reference/architecture/overview.md).
+
+---
-OpenFrame CLI follows a layered architecture pattern with clear separation between the CLI interface, business logic, and external integrations:
+## High-Level Architecture
```mermaid
graph TB
- subgraph "User Interface Layer"
- CLI[CLI Commands]
- UI[Interactive UI]
- Wizard[Setup Wizards]
- end
-
- subgraph "Application Layer"
- Bootstrap[Bootstrap Orchestrator]
- ClusterMgr[Cluster Manager]
- ChartMgr[Chart Manager]
- DevTools[Development Tools]
- end
-
- subgraph "Provider Layer"
- K3DProvider[K3D Provider]
- HelmProvider[Helm Provider]
- ArgoCDProvider[ArgoCD Provider]
- TelepresenceProvider[Telepresence Provider]
- KubectlProvider[kubectl Provider]
- GitProvider[Git Provider]
+ subgraph CLI["CLI Layer (cmd/)"]
+ Root["root.go"]
+ BootstrapCmd["bootstrap"]
+ ClusterCmd["cluster/*"]
+ ChartCmd["chart/*"]
+ DevCmd["dev/*"]
end
-
- subgraph "Infrastructure Layer"
- Executor[Command Executor]
- Config[Configuration]
- Logger[Logging]
- ErrorHandler[Error Handling]
- FileSystem[File Operations]
- end
-
- subgraph "External Systems"
- Docker[Docker Engine]
- K8s[Kubernetes API]
- Git[Git Repositories]
- Registry[Container Registry]
- ArgoCD[ArgoCD Server]
+
+ subgraph Services["Internal Services (internal/)"]
+ BootstrapSvc["bootstrap.Service"]
+ ClusterSvc["cluster.ClusterService"]
+ ChartSvc["chart.ChartService"]
+ InterceptSvc["intercept.Service"]
+ ScaffoldSvc["scaffold.Service"]
end
-
- CLI --> Bootstrap
- CLI --> ClusterMgr
- CLI --> ChartMgr
- CLI --> DevTools
-
- Bootstrap --> ClusterMgr
- Bootstrap --> ChartMgr
- ClusterMgr --> K3DProvider
- ChartMgr --> HelmProvider
- ChartMgr --> ArgoCDProvider
- DevTools --> TelepresenceProvider
- DevTools --> KubectlProvider
-
- K3DProvider --> Executor
- HelmProvider --> Executor
- ArgoCDProvider --> Executor
- TelepresenceProvider --> Executor
- KubectlProvider --> Executor
- GitProvider --> Executor
-
- K3DProvider --> Docker
- HelmProvider --> K8s
- ArgoCDProvider --> ArgoCD
- TelepresenceProvider --> K8s
- KubectlProvider --> K8s
- GitProvider --> Git
-```
-## Core Components
+ subgraph Providers["External Tool Providers"]
+ K3dProv["k3d.Manager"]
+ HelmProv["helm.HelmManager"]
+ ArgoCDProv["argocd.Manager"]
+ GitProv["git.Repository"]
+ KubectlProv["kubectl.Provider"]
+ TeleProv["telepresence.Provider"]
+ end
-### Command Layer (`cmd/`)
+ subgraph Shared["Shared Infrastructure (internal/shared/)"]
+ Executor["executor (cmd abstraction)"]
+ Errors["errors (structured types)"]
+ UI["ui (pterm / promptui)"]
+ Config["config (TLS / credentials)"]
+ end
-The command layer implements the CLI interface using the Cobra framework:
+ subgraph External["External Tools"]
+ K3D["K3D"]
+ Helm["Helm"]
+ ArgoCD["ArgoCD"]
+ Git["Git"]
+ Telepresence["Telepresence"]
+ Skaffold["Skaffold"]
+ Docker["Docker"]
+ Kubectl["kubectl"]
+ end
-| Component | Purpose | Key Features |
-|-----------|---------|--------------|
-| **Root Command** | Entry point and version management | Interactive help, global flags, subcommand routing |
-| **Bootstrap Command** | Complete environment setup | Orchestrates cluster + chart installation |
-| **Cluster Commands** | Kubernetes cluster lifecycle | Create, delete, list, status operations |
-| **Chart Commands** | Application deployment | Helm charts, ArgoCD applications |
-| **Dev Commands** | Development workflows | Service intercepts, scaffolding |
+ Root --> BootstrapCmd
+ Root --> ClusterCmd
+ Root --> ChartCmd
+ Root --> DevCmd
+
+ BootstrapCmd --> BootstrapSvc
+ ClusterCmd --> ClusterSvc
+ ChartCmd --> ChartSvc
+ DevCmd --> InterceptSvc
+ DevCmd --> ScaffoldSvc
+
+ BootstrapSvc --> ClusterSvc
+ BootstrapSvc --> ChartSvc
+
+ ClusterSvc --> K3dProv
+ ChartSvc --> HelmProv
+ ChartSvc --> ArgoCDProv
+ ChartSvc --> GitProv
+ InterceptSvc --> KubectlProv
+ InterceptSvc --> TeleProv
+ ScaffoldSvc --> KubectlProv
+ ScaffoldSvc --> ChartSvc
+
+ K3dProv --> K3D
+ HelmProv --> Helm
+ ArgoCDProv --> ArgoCD
+ GitProv --> Git
+ TeleProv --> Telepresence
+ ScaffoldSvc --> Skaffold
+ K3dProv --> Docker
+ KubectlProv --> Kubectl
+
+ ClusterSvc --> Shared
+ ChartSvc --> Shared
+ InterceptSvc --> Shared
+ ScaffoldSvc --> Shared
+```
-### Service Layer (`internal/`)
+---
-The service layer contains the core business logic:
+## Core Components
-#### Bootstrap Service (`internal/bootstrap/`)
-- **Purpose**: Orchestrates complete environment setup
-- **Key Functions**:
- - Validates prerequisites
- - Creates Kubernetes clusters
- - Installs core charts (ArgoCD, Traefik)
- - Configures GitOps workflows
+| Package | Path | Responsibility |
+|---|---|---|
+| **Root Command** | `cmd/root.go` | Entry point; wires all subcommands, version info, global flags |
+| **Bootstrap Command** | `cmd/bootstrap/` | Orchestrates cluster creation + chart installation in one command |
+| **Cluster Command** | `cmd/cluster/` | Subcommands: create, delete, list, status, cleanup |
+| **Chart Command** | `cmd/chart/` | Subcommands: install (ArgoCD + app-of-apps) |
+| **Dev Command** | `cmd/dev/` | Subcommands: intercept, skaffold |
+| **Bootstrap Service** | `internal/bootstrap/service.go` | Sequentially calls cluster create then chart install; handles Windows WSL init |
+| **Cluster Service** | `internal/cluster/service.go` | Business logic for cluster lifecycle; wraps K3D manager |
+| **K3D Manager** | `internal/cluster/providers/k3d/manager.go` | Low-level K3D operations via CLI; produces `rest.Config` |
+| **Chart Service** | `internal/chart/services/chart_service.go` | Orchestrates ArgoCD + app-of-apps installation workflow |
+| **Helm Manager** | `internal/chart/providers/helm/manager.go` | Helm operations using native Go clients + kubectl fallback |
+| **ArgoCD Manager** | `internal/chart/providers/argocd/applications.go` | Watches ArgoCD application health/sync via native K8s clients |
+| **Git Repository** | `internal/chart/providers/git/repository.go` | Shallow-clones app-of-apps chart repo to temp dir |
+| **Intercept Service** | `internal/dev/services/intercept/service.go` | Manages Telepresence intercept lifecycle |
+| **Scaffold Service** | `internal/dev/services/scaffold/service.go` | Runs Skaffold dev workflow with cluster bootstrap |
+| **Configuration Wizard** | `internal/chart/ui/configuration/wizard.go` | Interactive Helm values configuration wizard |
+| **Shared Executor** | `internal/shared/executor/executor.go` | Command execution abstraction (real + mock); handles WSL on Windows |
+| **Shared Errors** | `internal/shared/errors/errors.go` | Structured error types, retry policies, user-friendly display |
+| **Shared UI** | `internal/shared/ui/` | Prompts, tables, logo, progress tracking via pterm/promptui |
+
+---
+
+## Bootstrap Command Data Flow
+
+The most important flow is the `bootstrap` command, which orchestrates the full environment setup:
```mermaid
sequenceDiagram
participant User
- participant Bootstrap
- participant Cluster
- participant Chart
- participant ArgoCD
-
- User->>Bootstrap: openframe bootstrap
- Bootstrap->>Bootstrap: Check prerequisites
- Bootstrap->>Cluster: Create K3D cluster
- Cluster-->>Bootstrap: Cluster ready
- Bootstrap->>Chart: Install ArgoCD
- Chart-->>Bootstrap: ArgoCD installed
- Bootstrap->>ArgoCD: Deploy app-of-apps
- ArgoCD-->>Bootstrap: Applications synced
- Bootstrap-->>User: Environment ready
-```
-
-#### Cluster Service (`internal/cluster/`)
-- **Purpose**: Manages Kubernetes cluster lifecycle
-- **Key Functions**:
- - K3D cluster creation and deletion
- - Cluster status monitoring
- - Node management and scaling
- - Configuration and context management
-
-#### Chart Service (`internal/chart/`)
-- **Purpose**: Manages application deployments
-- **Key Functions**:
- - Helm chart installation
- - ArgoCD application management
- - GitOps workflow configuration
- - Application synchronization monitoring
-
-#### Development Services (`internal/dev/`)
-- **Purpose**: Provides development workflow tools
-- **Key Functions**:
- - Service intercepts with Telepresence
- - Code scaffolding and templates
- - Local development environment setup
- - Debug and testing utilities
-
-### Provider Layer
-
-The provider layer abstracts external tool integrations:
-
-#### K3D Provider (`internal/cluster/providers/k3d/`)
-```go
-type Manager interface {
- CreateCluster(config ClusterConfig) (*rest.Config, error)
- DeleteCluster(name string) error
- ListClusters() ([]ClusterInfo, error)
- GetClusterStatus(name string) (*ClusterStatus, error)
-}
-```
-
-Key responsibilities:
-- Docker container management for K3D nodes
-- Kubernetes API server configuration
-- Network and port forwarding setup
-- Cluster lifecycle management
-
-#### Helm Provider (`internal/chart/providers/helm/`)
-```go
-type Manager interface {
- InstallChart(release string, chart string, values map[string]interface{}) error
- UpgradeChart(release string, chart string, values map[string]interface{}) error
- UninstallChart(release string) error
- ListReleases() ([]Release, error)
-}
-```
-
-Key responsibilities:
-- Helm repository management
-- Chart installation and upgrades
-- Release lifecycle management
-- Value overrides and templating
-
-#### ArgoCD Provider (`internal/chart/providers/argocd/`)
-```go
-type Manager interface {
- CreateApplication(app ApplicationSpec) error
- SyncApplication(name string) error
- DeleteApplication(name string) error
- WaitForSync(name string, timeout time.Duration) error
-}
+ participant CLI as "openframe bootstrap"
+ participant Bootstrap as "bootstrap.Service"
+ participant ClusterSvc as "cluster.ClusterService"
+ participant K3dMgr as "k3d.Manager"
+ participant ChartSvc as "chart.ChartService"
+ participant HelmMgr as "helm.HelmManager"
+ participant ArgoCDMgr as "argocd.Manager"
+ participant GitRepo as "git.Repository"
+
+ User->>CLI: openframe bootstrap [name]
+ CLI->>Bootstrap: Execute(cmd, args)
+ Bootstrap->>Bootstrap: Validate flags
+
+ Bootstrap->>ClusterSvc: CreateClusterWithPrerequisites()
+ ClusterSvc->>ClusterSvc: CheckPrerequisites (Docker, k3d, kubectl, helm)
+ ClusterSvc->>K3dMgr: CreateCluster(config)
+ K3dMgr-->>ClusterSvc: rest.Config
+ ClusterSvc-->>Bootstrap: rest.Config
+
+ Bootstrap->>ChartSvc: InstallChartsWithConfig(request)
+ ChartSvc->>ChartSvc: CheckPrerequisites (git, helm, mkcert)
+ ChartSvc->>ChartSvc: ConfigureHelmValues (wizard)
+
+ ChartSvc->>HelmMgr: InstallArgoCD(ctx, config)
+ HelmMgr-->>ChartSvc: ArgoCD installed
+
+ ChartSvc->>GitRepo: CloneChartRepository(appOfAppsConfig)
+ GitRepo-->>ChartSvc: CloneResult (tempDir, chartPath)
+
+ ChartSvc->>HelmMgr: InstallAppOfApps(ctx, config)
+ HelmMgr-->>ChartSvc: app-of-apps installed
+
+ ChartSvc->>ArgoCDMgr: WaitForApplications(ctx, config)
+ ArgoCDMgr->>ArgoCDMgr: Poll ArgoCD Application CRDs
+ ArgoCDMgr-->>ChartSvc: All apps Healthy + Synced
+
+ ChartSvc-->>Bootstrap: success
+ Bootstrap-->>CLI: success
+ CLI-->>User: Bootstrap complete
```
-Key responsibilities:
-- ArgoCD application CRD management
-- Git repository synchronization
-- Application health monitoring
-- Sync policy configuration
-
-### Shared Infrastructure (`internal/shared/`)
-
-Common utilities and cross-cutting concerns:
-
-#### Command Executor (`internal/shared/executor/`)
-- **Purpose**: Standardized external command execution
-- **Features**:
- - Command building and execution
- - Output capture and streaming
- - Error handling and retry logic
- - Timeout management
- - Mock support for testing
-
-#### Configuration Management (`internal/shared/config/`)
-- **Purpose**: Application configuration and settings
-- **Features**:
- - YAML/JSON configuration files
- - Environment variable overrides
- - Default value management
- - Validation and type safety
+---
-#### User Interface (`internal/shared/ui/`)
-- **Purpose**: Consistent user interaction patterns
-- **Features**:
- - Interactive prompts and wizards
- - Progress indicators and spinners
- - Colored output and formatting
- - Table rendering and alignment
- - Error message presentation
+## Configuration Wizard Flow
-## Data Flow Architecture
-
-### Bootstrap Workflow
-
-The bootstrap process follows a carefully orchestrated sequence:
+The interactive chart installation flow guides operators through Helm values configuration:
```mermaid
-flowchart TD
- A[Start Bootstrap] --> B[Check Prerequisites]
- B --> C{Prerequisites OK?}
- C -->|No| D[Install Missing Tools]
- C -->|Yes| E[Validate Configuration]
- D --> E
- E --> F[Create K3D Cluster]
- F --> G[Wait for Cluster Ready]
- G --> H[Install ArgoCD]
- H --> I[Configure Git Repositories]
- I --> J[Deploy App-of-Apps]
- J --> K[Wait for Application Sync]
- K --> L{All Apps Healthy?}
- L -->|No| M[Troubleshoot & Retry]
- L -->|Yes| N[Bootstrap Complete]
- M --> K
-```
-
-### Service Interaction Patterns
-
-Services interact through well-defined interfaces:
-
-```mermaid
-classDiagram
- class BootstrapService {
- +Execute(config BootstrapConfig) error
- -validatePrerequisites() error
- -createCluster() error
- -installCharts() error
- }
-
- class ClusterService {
- +Create(name string) error
- +Delete(name string) error
- +Status(name string) ClusterStatus
- +List() []ClusterInfo
- }
-
- class ChartService {
- +Install(chart ChartSpec) error
- +List() []ChartInfo
- +Sync(name string) error
- +WaitForReady(name string) error
- }
-
- BootstrapService --> ClusterService
- BootstrapService --> ChartService
- ChartService --> ArgocdProvider
- ClusterService --> K3dProvider
+sequenceDiagram
+ participant User
+ participant Workflow as "InstallationWorkflow"
+ participant Wizard as "ConfigurationWizard"
+ participant Modifier as "HelmValuesModifier"
+ participant Installer as "chart.Installer"
+
+ User->>Workflow: ExecuteWithContext(ctx, req)
+ Workflow->>Workflow: SelectCluster (interactive or arg)
+ Workflow->>Wizard: ConfigureHelmValues()
+ Wizard->>User: Select deployment mode (oss-tenant / saas-tenant / saas-shared)
+ User-->>Wizard: oss-tenant
+ Wizard->>User: Select config mode (default / interactive)
+ User-->>Wizard: interactive
+ Wizard->>Modifier: LoadOrCreateBaseValues()
+ Modifier-->>Wizard: map of values
+ Wizard->>User: Configure branch / Docker / Ingress
+ User-->>Wizard: selections
+ Wizard->>Modifier: ApplyConfiguration(values, config)
+ Wizard->>Modifier: CreateTemporaryValuesFile(values)
+ Modifier-->>Wizard: helm-values-tmp.yaml
+ Wizard-->>Workflow: ChartConfiguration
+
+ Workflow->>Installer: InstallChartsWithContext(ctx, config)
+ Installer->>Installer: ArgoCD install
+ Installer->>Installer: app-of-apps install
+ Installer->>Installer: WaitForApplications
+ Installer-->>Workflow: success
```
-## Key Design Decisions
-
-### 1. Layered Architecture
-
-**Decision**: Implement strict layering with dependency injection
-**Rationale**:
-- Clear separation of concerns
-- Easier testing through interface mocking
-- Flexibility to swap implementations
-- Maintainable and extensible codebase
-
-### 2. Provider Pattern
-
-**Decision**: Abstract external tools behind provider interfaces
-**Rationale**:
-- Support multiple Kubernetes distributions (K3D, Kind, etc.)
-- Enable testing without external dependencies
-- Simplify adding new tool integrations
-- Consistent error handling and logging
+---
-### 3. Command Executor Abstraction
+## Dependency Injection Pattern
-**Decision**: Centralize external command execution
-**Rationale**:
-- Consistent error handling across all external calls
-- Unified logging and debugging capabilities
-- Simplified testing with command mocking
-- Retry logic and timeout management
-
-### 4. Interactive CLI Design
-
-**Decision**: Provide both interactive and non-interactive modes
-**Rationale**:
-- User-friendly for manual operations
-- Scriptable for automation and CI/CD
-- Progressive disclosure of complexity
-- Clear error messages and guidance
-
-### 5. GitOps-First Approach
-
-**Decision**: Default to GitOps workflows with ArgoCD
-**Rationale**:
-- Industry best practices for Kubernetes deployments
-- Declarative infrastructure management
-- Audit trails and rollback capabilities
-- Team collaboration through Git workflows
-
-## Error Handling Strategy
-
-### Error Types and Handling
+The CLI uses constructor injection throughout. The `CommandExecutor` interface is the central abstraction that makes the entire CLI unit-testable without running real tools:
```mermaid
-graph TD
- A[Error Occurs] --> B{Error Type?}
- B -->|Validation Error| C[Show Usage Help]
- B -->|External Tool Error| D[Parse Tool Output]
- B -->|Network Error| E[Suggest Connectivity Check]
- B -->|Resource Error| F[Check Resource Availability]
-
- C --> G[Exit with Code 1]
- D --> H{Recoverable?}
- E --> H
- F --> H
-
- H -->|Yes| I[Retry with Backoff]
- H -->|No| J[Show Error + Solutions]
-
- I --> K{Max Retries?}
- K -->|No| A
- K -->|Yes| J
-
- J --> G
+graph LR
+ TestCode["Test Code"] --> MockExec["MockCommandExecutor"]
+ ProdCode["Production Code"] --> RealExec["RealCommandExecutor"]
+ MockExec --> ExecInterface["CommandExecutor (interface)"]
+ RealExec --> ExecInterface
+ ExecInterface --> Services["All Services"]
+ Services --> Providers["All Providers"]
```
-### Error Categories
-
-| Category | Examples | Handling Strategy |
-|----------|----------|------------------|
-| **User Input** | Invalid flags, missing config | Show usage help, suggest corrections |
-| **Prerequisites** | Missing tools, permissions | Guide installation, check prerequisites |
-| **Network** | Connection timeouts, DNS issues | Retry with backoff, check connectivity |
-| **Resource** | Insufficient memory, disk space | Check resources, suggest alternatives |
-| **External Tools** | kubectl errors, helm failures | Parse tool output, provide context |
-
-## Configuration Architecture
-
-### Configuration Sources (Priority Order)
-
-1. **Command-line flags** - Highest priority
-2. **Environment variables** - Override config files
-3. **Configuration files** - User and system configs
-4. **Default values** - Built-in sensible defaults
-
-### Configuration Structure
-
-```yaml
-# ~/.openframe/config.yaml
-openframe:
- log_level: "info"
- config_dir: "~/.openframe"
-
-cluster:
- provider: "k3d"
- default_name: "openframe-local"
- nodes: 1
-
-bootstrap:
- mode: "oss-tenant"
- timeout: "15m"
- interactive: true
-
-chart:
- timeout: "10m"
- wait_for_ready: true
-
-dev:
- intercept_timeout: "5m"
- scaffold_template_dir: "~/.openframe/templates"
-```
+All services accept a `CommandExecutor` via their constructors. In production this is `executor.NewRealExecutor()`. In tests this is `testutil.NewTestMockExecutor()`.
-## Testing Architecture
+---
-### Test Strategy
+## Error Handling Architecture
-```mermaid
-graph TB
- subgraph "Unit Tests"
- A[Service Logic Tests]
- B[Provider Tests with Mocks]
- C[Utility Function Tests]
- end
-
- subgraph "Integration Tests"
- D[End-to-End Command Tests]
- E[Provider Integration Tests]
- F[External Tool Integration]
- end
-
- subgraph "Acceptance Tests"
- G[Complete Bootstrap Workflow]
- H[Multi-Cluster Scenarios]
- I[Development Workflow Tests]
- end
-
- A --> D
- B --> E
- C --> F
- D --> G
- E --> H
- F --> I
-```
+Errors in the CLI follow a structured pattern using custom error types:
-### Mock Strategy
+| Error Type | When Used |
+|---|---|
+| `ValidationError` | Field validation failures (flag values, cluster names, ports) |
+| `CommandError` | External tool execution failures (k3d, helm, kubectl) |
+| `BranchNotFoundError` | Git branch not found in chart repositories |
+| `AlreadyHandledError` | Errors already displayed — prevents double-showing |
-- **External Commands**: Mock command executor for tool interactions
-- **Kubernetes API**: Use fake clientsets for API testing
-- **File System**: Mock file operations for config testing
-- **Network**: Mock HTTP clients for external service calls
+The `ErrorHandler` routes errors to appropriate display logic based on type, using pterm for colored, user-friendly output with troubleshooting guidance.
-## Security Architecture
+---
-### Security Principles
+## Prerequisite System
-1. **Least Privilege**: Request minimal permissions necessary
-2. **Secure Defaults**: Safe configurations out of the box
-3. **Input Validation**: Sanitize all user inputs
-4. **Secret Management**: Secure handling of credentials and keys
-5. **Audit Logging**: Track security-relevant operations
-
-### Trust Boundaries
+Each command group has its own prerequisite checker:
```mermaid
-graph LR
- subgraph "Trusted Zone"
- A[OpenFrame CLI]
- B[Local Kubernetes]
- C[Local Docker]
- end
-
- subgraph "Semi-Trusted Zone"
- D[Container Images]
- E[Helm Charts]
- F[Git Repositories]
- end
-
- subgraph "Untrusted Zone"
- G[Public Internet]
- H[External APIs]
- I[User Input]
- end
-
- A --> B
- A --> C
- B --> D
- A --> E
- A --> F
-
- E --> G
- F --> G
- A --> H
- I --> A
+graph TD
+ ClusterOps["Cluster Operations"] --> ClusterPrereqs["Docker, kubectl, k3d, Helm"]
+ ChartOps["Chart Operations"] --> ChartPrereqs["Git, Helm, mkcert, Memory check"]
+ DevOps["Dev Operations"] --> DevPrereqs["Telepresence, jq, Skaffold"]
+ ClusterPrereqs --> PrereqChecker["PrerequisiteChecker"]
+ ChartPrereqs --> PrereqChecker
+ DevPrereqs --> PrereqChecker
+ PrereqChecker --> InstallGuide["Platform-specific install guidance"]
```
-## Performance Considerations
-
-### Optimization Strategies
-
-1. **Lazy Loading**: Load providers and tools only when needed
-2. **Concurrent Operations**: Parallel execution where safe
-3. **Caching**: Cache expensive operations (cluster status, etc.)
-4. **Resource Monitoring**: Track memory and CPU usage
-5. **Efficient Data Structures**: Use appropriate data types
-
-### Resource Management
-
-- **Memory**: Stream large outputs, avoid loading everything in memory
-- **CPU**: Use worker pools for concurrent operations
-- **Disk**: Clean up temporary files, use appropriate buffer sizes
-- **Network**: Connection pooling, request batching where possible
-
-## Extensibility Points
-
-### Adding New Commands
-
-1. **Create command file** in appropriate `cmd/` subdirectory
-2. **Implement service logic** in `internal/` package
-3. **Add provider interface** if external tool needed
-4. **Write comprehensive tests** for all components
-5. **Update documentation** and help text
+Prerequisite checkers detect CI environments and skip interactive prompts automatically.
-### Adding New Providers
+---
-1. **Define provider interface** in appropriate service package
-2. **Implement provider** in `internal/*/providers/` directory
-3. **Add configuration support** for provider-specific settings
-4. **Implement comprehensive testing** including mocks
-5. **Update factory functions** to instantiate new provider
-
-### Plugin Architecture (Future)
-
-Future extensibility through plugins:
-
-```mermaid
-graph TB
- A[OpenFrame Core] --> B[Plugin Manager]
- B --> C[Command Plugins]
- B --> D[Provider Plugins]
- B --> E[UI Plugins]
-
- C --> F[Custom Commands]
- D --> G[New Tool Integrations]
- E --> H[Custom Interfaces]
-```
-
-## Migration and Upgrade Strategy
+## Key Design Decisions
-### Backward Compatibility
+1. **Interface-first providers** — All external tool interactions go through interfaces defined in `internal/*/utils/types/interfaces.go`, enabling full mockability in tests.
-- **Configuration**: Support old config format with migration
-- **Commands**: Maintain command compatibility across versions
-- **Data**: Migrate user data automatically when needed
-- **Dependencies**: Graceful handling of version mismatches
+2. **Shared executor abstraction** — The `CommandExecutor` interface centralizes all shell command execution, with WSL2 wrapping built in for Windows.
-### Version Management
+3. **Structured error types** — Custom error types provide rich context for user-friendly display and enable programmatic error handling.
-```go
-type VersionInfo struct {
- Version string // Semantic version
- Commit string // Git commit hash
- Date string // Build timestamp
- Go string // Go version used
-}
-```
+4. **Deferred Helm initialization** — The Helm manager defers Go client initialization until first use, preventing startup overhead for commands that don't need it.
-## Next Steps
+5. **App-of-apps GitOps pattern** — The CLI shallow-clones the chart repository to a temp directory and installs locally, avoiding the need for a running chart server.
-To deepen your understanding of OpenFrame CLI architecture:
+---
-1. **[Security Guidelines](../security/README.md)** - Learn about security implementations
-2. **[Testing Guide](../testing/README.md)** - Understand testing strategies
-3. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn development processes
+## Reference Documentation
-## Additional Resources
+For detailed per-component documentation, see the auto-generated reference:
-- **[Architecture Documentation](./architecture/overview.md)** - Generated architecture docs from code
-- **Go Design Patterns**: https://golang.org/doc/effective_go
-- **Kubernetes Client Libraries**: https://kubernetes.io/docs/reference/using-api/client-libraries/
-- **Cobra CLI Framework**: https://cobra.dev/
-- **OpenMSP Community**: [Join Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
\ No newline at end of file
+- [Architecture Reference](./reference/architecture/overview.md) — Full CodeWiki output with complete component details
diff --git a/docs/development/contributing/guidelines.md b/docs/development/contributing/guidelines.md
new file mode 100644
index 00000000..95059f68
--- /dev/null
+++ b/docs/development/contributing/guidelines.md
@@ -0,0 +1,259 @@
+# Contributing Guidelines
+
+Thank you for contributing to OpenFrame CLI! This guide covers everything you need to know about code style, branching strategy, pull requests, and the review process.
+
+> **Community support happens in Slack, not GitHub Issues.**
+> Join the [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) to discuss contributions, ask questions, or report bugs before opening a PR.
+
+---
+
+## Code Style and Conventions
+
+### Go Style Guide
+
+OpenFrame CLI follows standard Go conventions with a few project-specific rules:
+
+- **Format with `gofmt`**: All code must be formatted with `gofmt` before committing
+- **Organize imports with `goimports`**: Use `goimports` for import grouping (stdlib, external, internal)
+- **Lint with `golangci-lint`**: All linter rules must pass before a PR can merge
+- **Error wrapping**: Use `fmt.Errorf("operation failed: %w", err)` for wrapping errors
+- **Context propagation**: All service methods that call external tools must accept and propagate `context.Context`
+- **Interface-first**: New external tool integrations must be defined as interfaces before implementation
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---|---|---|
+| Packages | lowercase, single word | `cluster`, `executor`, `argocd` |
+| Exported types | PascalCase | `ClusterService`, `K3dManager` |
+| Unexported types | camelCase | `clusterConfig`, `helmValues` |
+| Interfaces | Noun or `er` suffix | `ClusterManager`, `CommandExecutor` |
+| Test functions | `Test` | `TestCreateCluster` |
+| Test files | `_test.go` | `service_test.go` |
+| Constructor functions | `New()` | `NewK3dManager()`, `NewClusterService()` |
+
+### Error Handling Conventions
+
+```go
+// ✅ CORRECT — wrap with context
+if err := someOperation(); err != nil {
+ return fmt.Errorf("creating cluster %s: %w", name, err)
+}
+
+// ✅ CORRECT — use structured error types for user-facing errors
+return errors.CreateCommandError("k3d", args, originalErr)
+
+// ❌ WRONG — discarding context
+if err := someOperation(); err != nil {
+ return err
+}
+
+// ❌ WRONG — using errors.New when wrapping
+return errors.New("operation failed")
+```
+
+### Logging and Output
+
+- **Never use `fmt.Println` in service/provider code** — all user-facing output must go through `internal/shared/ui`
+- **Verbose output**: Wrap detailed logs in verbose-mode checks
+- **No secrets in logs**: Never log credential values, tokens, or passwords — even in verbose mode
+
+---
+
+## Branch Naming Convention
+
+| Branch Type | Format | Example |
+|---|---|---|
+| Feature | `feature/` | `feature/add-cluster-pause-command` |
+| Bug fix | `fix/` | `fix/k3d-timeout-on-slow-machines` |
+| Documentation | `docs/` | `docs/add-telepresence-guide` |
+| Refactor | `refactor/` | `refactor/executor-interface-cleanup` |
+| Release | `release/v..` | `release/v1.2.0` |
+
+**Rules:**
+- Use lowercase only
+- Use hyphens as word separators (not underscores or spaces)
+- Keep descriptions short (2–5 words)
+- Branch off `main` for all new work
+
+```bash
+# Create a new feature branch
+git checkout main
+git pull origin main
+git checkout -b feature/my-new-feature
+```
+
+---
+
+## Commit Message Format
+
+OpenFrame CLI uses the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```text
+():
+
+[optional body]
+
+[optional footer]
+```
+
+### Commit Types
+
+| Type | When to Use |
+|---|---|
+| `feat` | A new feature or capability |
+| `fix` | A bug fix |
+| `docs` | Documentation changes only |
+| `style` | Formatting, missing semicolons, no logic change |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `test` | Adding or updating tests |
+| `chore` | Build process, dependency updates, tooling changes |
+| `perf` | Performance improvements |
+
+### Scope Examples
+
+```text
+feat(cluster): add pause/resume cluster commands
+fix(chart): resolve ArgoCD wait timeout on slow machines
+docs(bootstrap): update non-interactive flag documentation
+test(executor): add mock response for k3d list command
+refactor(shared): consolidate error display in ErrorHandler
+chore(deps): update client-go to v0.29.0
+```
+
+### Commit Message Rules
+
+- Subject line: 72 characters max, imperative mood ("add X", not "added X" or "adds X")
+- No period at the end of the subject line
+- Body: wrap at 72 characters; explain *what* and *why*, not *how*
+- Reference issues/discussions in the footer: `Closes #123` or `Fixes #456`
+
+---
+
+## Pull Request Process
+
+### Before Opening a PR
+
+Complete this checklist:
+
+- [ ] Code is formatted with `gofmt` and `goimports`
+- [ ] All linter rules pass: `golangci-lint run ./...`
+- [ ] All tests pass: `go test ./...`
+- [ ] New code has corresponding unit tests
+- [ ] Vulnerability check passes: `govulncheck ./...`
+- [ ] PR description explains *what* changed and *why*
+
+### PR Title
+
+Follow the same Conventional Commits format as commit messages:
+
+```text
+feat(cluster): add cluster pause/resume subcommands
+fix(chart): handle ArgoCD sync timeout gracefully
+docs(dev): improve Telepresence intercept documentation
+```
+
+### PR Description Template
+
+```markdown
+## Summary
+Brief description of what this PR does and why.
+
+## Changes
+- Added `openframe cluster pause` command
+- Added `openframe cluster resume` command
+- Updated ClusterService with pause/resume methods
+- Added unit tests for pause/resume operations
+
+## Testing
+Describe how you tested these changes:
+- Unit tests: `go test ./internal/cluster/...`
+- Manual test: `./openframe cluster pause test-cluster`
+
+## Related
+Link to Slack discussion or related context (if applicable).
+```
+
+---
+
+## Review Checklist
+
+When reviewing a PR, check the following:
+
+### Code Quality
+- [ ] Logic is clear and follows existing patterns
+- [ ] No unnecessary complexity or over-engineering
+- [ ] Error messages are user-friendly and actionable
+- [ ] No hardcoded values that should be configurable
+
+### Architecture
+- [ ] New external tools are abstracted behind interfaces
+- [ ] Dependencies are injected (not instantiated inline in service methods)
+- [ ] Commands delegate to services; services delegate to providers
+- [ ] Shared infrastructure is used (don't re-implement logging, prompts, errors)
+
+### Testing
+- [ ] Unit tests cover the happy path
+- [ ] Unit tests cover error cases
+- [ ] Mock executor is used correctly (no real tool calls in unit tests)
+- [ ] New prerequisite tools have installer tests
+
+### Security
+- [ ] No credentials or secrets in source code
+- [ ] All user inputs are validated
+- [ ] External commands use `exec.Command` with arg arrays (not shell strings)
+- [ ] Temporary files are cleaned up with `defer`
+
+### Documentation
+- [ ] Exported functions and types have Go doc comments
+- [ ] New commands have `Short` and `Long` descriptions in the Cobra command
+- [ ] README or CHANGELOG updated if user-facing behavior changed
+
+---
+
+## Local Validation Before Submitting
+
+Run this sequence before opening a PR:
+
+```bash
+# Format code
+gofmt -w .
+goimports -w .
+
+# Lint
+golangci-lint run ./...
+
+# Test
+go test ./...
+
+# Vulnerability check
+govulncheck ./...
+
+# Build check
+go build -o /tmp/openframe-test ./main.go
+```
+
+---
+
+## Adding New Commands
+
+When adding a new command, follow this pattern:
+
+1. **Create the command file**: `cmd//.go`
+2. **Register in group file**: Add to `cmd//.go`'s `AddCommand()` call
+3. **Create service logic**: `internal//services/.go`
+4. **Define interface**: Add to `internal//utils/types/interfaces.go`
+5. **Add prerequisite checks**: Update `internal//prerequisites/checker.go` if needed
+6. **Write unit tests**: `internal//services/_test.go`
+7. **Update inline docs**: Exported functions and types must have doc comments
+
+---
+
+## Getting Help
+
+Stuck on something? The best place to ask is the **OpenMSP Slack**:
+
+- **Join**: [openmsp.ai](https://www.openmsp.ai/)
+- **Slack invite**: [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+
+Discuss your contribution idea in Slack before starting large changes — this avoids duplicated effort and ensures alignment with the project's direction.
diff --git a/docs/development/security/README.md b/docs/development/security/README.md
new file mode 100644
index 00000000..c2de3ea6
--- /dev/null
+++ b/docs/development/security/README.md
@@ -0,0 +1,257 @@
+# Security Best Practices
+
+This guide covers security considerations for developing, deploying, and operating OpenFrame CLI. It addresses credential management, TLS configuration, secrets handling, and secure development practices.
+
+---
+
+## Overview
+
+OpenFrame CLI interacts with several sensitive systems:
+
+- **Kubernetes clusters** — via kubeconfig and REST API
+- **Docker registries** — with optional authentication
+- **GitHub repositories** — via personal access tokens (PATs) or SSH
+- **Helm chart repositories** — with potential authentication
+- **ArgoCD** — via Kubernetes RBAC
+
+Security is a shared responsibility between the CLI, the operator's environment, and the underlying platform.
+
+---
+
+## Authentication and Authorization
+
+### Kubernetes Access
+
+The CLI uses standard Kubernetes authentication via kubeconfig. It calls `clientcmd.BuildConfigFromFlags` to load the kubeconfig from the default location or the `KUBECONFIG` environment variable.
+
+**Best practices:**
+
+- Use separate kubeconfig files or contexts for each environment (dev, staging, production)
+- Rotate kubeconfig credentials regularly
+- Never commit kubeconfig files to version control
+- Use RBAC-scoped service accounts for CI/CD pipelines — avoid using admin credentials in automated workflows
+
+```bash
+# Use environment variable to specify kubeconfig
+export KUBECONFIG="$HOME/.kube/openframe-dev-config"
+openframe cluster status my-cluster
+```
+
+### GitHub Credentials
+
+When the chart installation requires cloning private repositories, the CLI prompts for GitHub credentials via the `CredentialsPrompter`:
+
+```text
+Enter your GitHub credentials for https://github.com/org/private-repo:
+Username: your-github-username
+Token: **** (personal access token)
+```
+
+**Best practices:**
+
+- Use **GitHub Personal Access Tokens (PATs)** with the minimum required scopes — typically `repo` (read-only) is sufficient for chart cloning
+- Use **fine-grained PATs** scoped to specific repositories where possible
+- Rotate PATs regularly (every 90 days recommended)
+- Never hardcode PATs in scripts or environment files that get committed
+
+### Docker Registry Credentials
+
+For deployments using private Docker registries:
+
+```text
+Enter Docker registry credentials for registry.example.com:
+Username: your-username
+Password: ****
+```
+
+**Best practices:**
+
+- Use short-lived registry credentials (e.g., via `docker login` with token-based auth)
+- Prefer image pull secrets in Kubernetes over embedding credentials in Helm values
+- Use read-only registry credentials for deployments
+
+---
+
+## Secrets Management
+
+### Environment Variables vs. Flags
+
+The CLI never stores credentials on disk between sessions. Credentials are:
+1. Prompted interactively at runtime
+2. Passed directly to the tool that needs them
+3. Never written to log files or stdout (passwords are masked)
+
+**What to avoid:**
+
+```bash
+# NEVER DO THIS — credentials visible in shell history and process list
+openframe chart install my-cluster --github-token=ghp_my_token
+```
+
+**Instead, use interactive prompts** which mask input and avoid shell history exposure.
+
+### Protecting Shell History
+
+If you must pass credentials via environment variables for CI/CD:
+
+```bash
+# Set in CI environment secrets, not in scripts
+export GITHUB_TOKEN="$(vault kv get -field=token secret/github)"
+```
+
+Use your CI/CD platform's native secrets management:
+- **GitHub Actions**: Repository Secrets (`${{ secrets.GITHUB_TOKEN }}`)
+- **GitLab CI**: CI/CD Variables (masked)
+- **Jenkins**: Credentials Store
+- **ArgoCD**: Sealed Secrets or External Secrets Operator
+
+---
+
+## TLS and Certificate Security
+
+### Local TLS with mkcert
+
+The CLI uses `mkcert` to generate locally trusted TLS certificates for K3D clusters. This ensures HTTPS works correctly in local development without certificate warnings.
+
+**How it works:**
+
+1. mkcert installs a local Certificate Authority (CA) into your system trust store
+2. The CLI generates a certificate signed by this local CA
+3. The certificate is used for the Kubernetes API server and ingress
+
+**Security considerations:**
+
+- The local CA is trusted **only on your machine** — certificates are not valid externally
+- Do not distribute local CA certificates to other machines
+- For production deployments, use certificates from a trusted public CA (Let's Encrypt, your organization's PKI)
+
+### TLS Configuration in Code
+
+The CLI applies an insecure TLS configuration for local K3D cluster connections:
+
+```go
+// internal/shared/config/transport.go
+// ApplyInsecureTLSConfig is used ONLY for local K3D clusters
+// Never use InsecureSkipVerify in production connections
+```
+
+> **Warning**: `InsecureSkipVerify` is enabled only for local K3D clusters (127.0.0.1 / localhost). This is acceptable for local development but must never be used for remote or production clusters.
+
+---
+
+## Input Validation and Sanitization
+
+### Cluster Name Validation
+
+The CLI validates cluster names before use via `ValidateClusterName`. Names are checked for:
+- Valid character sets (alphanumeric, hyphens)
+- Length limits
+- Reserved names
+
+### Port Validation
+
+Port numbers are validated before creating Telepresence intercepts:
+
+```go
+// Validation occurs in internal/dev/services/intercept/service.go
+// validateInputs() checks port ranges (1-65535) and service name format
+```
+
+### Flag Sanitization
+
+All user-provided flag values go through structured validation before being passed to external tools. The `ValidationError` type provides field-level error reporting:
+
+```text
+✗ Validation failed:
+ Field: port
+ Value: "invalid"
+ Error: must be a valid port number (1-65535)
+```
+
+---
+
+## Common Security Vulnerabilities and Mitigations
+
+| Vulnerability | Risk | Mitigation |
+|---|---|---|
+| Credential exposure in logs | Passwords visible in verbose output | Passwords are always masked; never log credential values |
+| Command injection | User input passed to shell commands | All external commands use `exec.Command` with args array — no shell expansion |
+| Insecure TLS | MITM attacks on cluster connections | InsecureSkipVerify used only for `localhost`/`127.0.0.1` K3D clusters |
+| Kubeconfig exposure | Cluster access via leaked kubeconfig | Never log kubeconfig paths; use scoped contexts; rotate credentials |
+| Dependency vulnerabilities | CVEs in transitive Go dependencies | Run `govulncheck ./...` regularly; keep `go.sum` up to date |
+| Path traversal in temp files | Reading files outside temp directory | Temp directory cleanup via `defer` in `git.Repository` |
+
+---
+
+## Secure Handling of Temporary Files
+
+The CLI creates temporary files during chart installation (cloned repositories, temporary Helm values files). These are cleaned up via deferred functions:
+
+```go
+// internal/chart/providers/git/repository.go
+// Shallow clone goes to os.MkdirTemp() — always cleaned up via defer os.RemoveAll(tempDir)
+```
+
+**Best practices for operators:**
+
+- Ensure `/tmp` (or OS temp directory) is on an encrypted volume in sensitive environments
+- Monitor for unexpected files persisting after CLI operations (may indicate cleanup failures)
+
+---
+
+## Security Testing
+
+### Running Vulnerability Checks
+
+```bash
+# Check for known CVEs in Go dependencies
+govulncheck ./...
+
+# Check Go module dependencies for known vulnerabilities
+go list -m all | nancy sleuth
+```
+
+### Code Review Security Checklist
+
+When reviewing CLI changes, check for:
+
+- [ ] No credentials or secrets hardcoded in source or test files
+- [ ] All user-provided inputs are validated before use
+- [ ] External commands use `exec.Command` with separate args (not shell string interpolation)
+- [ ] Temporary files are created in OS temp directory and cleaned up with `defer`
+- [ ] No `InsecureSkipVerify` added outside the local K3D TLS helper
+- [ ] Verbose mode does not log credential values
+- [ ] Error messages do not expose internal paths or system information unnecessarily
+
+---
+
+## Environment Variables and Secrets in CI/CD
+
+For non-interactive CI/CD usage of the CLI:
+
+```bash
+# Bootstrap in CI — use platform secret management
+openframe bootstrap my-ci-cluster \
+ --deployment-mode=oss-tenant \
+ --non-interactive \
+ --github-branch=main
+```
+
+**CI security checklist:**
+
+- [ ] Store all tokens and credentials in your CI platform's secret store
+- [ ] Use short-lived credentials where possible
+- [ ] Rotate credentials after every major release pipeline
+- [ ] Audit CI logs to ensure no secrets are printed (check for masked values)
+- [ ] Use a dedicated service account for CI cluster operations, not personal credentials
+
+---
+
+## Reporting Security Issues
+
+Security vulnerabilities should be reported via the **OpenMSP Slack community** — not as public GitHub Issues.
+
+- **Slack**: [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+- **Community**: [openmsp.ai](https://www.openmsp.ai/)
+
+Please use a private Slack message to the maintainers for sensitive security disclosures.
diff --git a/docs/development/setup/environment.md b/docs/development/setup/environment.md
index 9f95aa1e..cac77892 100644
--- a/docs/development/setup/environment.md
+++ b/docs/development/setup/environment.md
@@ -1,621 +1,235 @@
# Development Environment Setup
-This guide walks you through setting up a complete development environment for OpenFrame CLI, including IDEs, tools, extensions, and configuration for maximum productivity.
+This guide covers the IDE configuration, development tools, and editor extensions recommended for contributing to OpenFrame CLI.
-## IDE and Editor Setup
+---
-### Visual Studio Code (Recommended)
+## Required Development Tools
-VS Code provides excellent Go support and Kubernetes tooling:
+| Tool | Version | Purpose |
+|---|---|---|
+| **Go** | 1.21+ | Primary language runtime and toolchain |
+| **Git** | 2.30+ | Version control |
+| **Docker** | 20.10+ | Required for running K3D clusters during development |
+| **k3d** | 5.6+ | Local Kubernetes cluster provider |
+| **kubectl** | 1.26+ | Kubernetes CLI for cluster interaction |
+| **Helm** | 3.12+ | Kubernetes package manager |
+| **mkcert** | 1.4+ | Local TLS certificate generation |
+| **Make** | 3.81+ | Build automation (optional but recommended) |
+
+---
+
+## Installing Go
+
+### macOS
-#### Installation
```bash
-# macOS
-brew install --cask visual-studio-code
-
-# Ubuntu/Debian
-wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
-sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/
-sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/trusted.gpg.d/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
-sudo apt update
-sudo apt install code
+brew install go
```
-#### Essential Extensions
+### Linux
+
+```bash
+# Download and install Go (replace version as needed)
+curl -L https://go.dev/dl/go1.21.13.linux-amd64.tar.gz | sudo tar -C /usr/local -xz
+echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
+source ~/.bashrc
+```
-Install these extensions for Go and Kubernetes development:
+### Verify
```bash
-# Core Go development
-code --install-extension golang.Go
-code --install-extension golang.Go-nightly
+go version
+# go version go1.21.x linux/amd64
+```
-# Kubernetes and YAML
-code --install-extension ms-kubernetes-tools.vscode-kubernetes-tools
-code --install-extension redhat.vscode-yaml
+---
-# Git and GitHub integration
-code --install-extension GitHub.vscode-pull-request-github
-code --install-extension eamodio.gitlens
+## Recommended IDE
-# Code quality and testing
-code --install-extension ms-vscode.test-adapter-converter
-code --install-extension hbenl.vscode-test-explorer
-code --install-extension SonarSource.sonarlint-vscode
+### Visual Studio Code
-# Docker and containers
-code --install-extension ms-azuretools.vscode-docker
+VS Code with the Go extension is the recommended IDE for OpenFrame CLI development.
-# Markdown and documentation
-code --install-extension yzhang.markdown-all-in-one
-code --install-extension bierner.markdown-mermaid
+**Install the Go extension:**
-# Productivity
-code --install-extension vscodevim.vim # Optional: Vim keybindings
-code --install-extension ms-vscode.vscode-json
+```bash
+code --install-extension golang.go
```
-#### VS Code Configuration
+**Recommended VS Code extensions:**
+
+| Extension | ID | Purpose |
+|---|---|---|
+| Go | `golang.go` | Go language support, IntelliSense, debugging |
+| GitLens | `eamodio.gitlens` | Enhanced Git integration |
+| YAML | `redhat.vscode-yaml` | YAML editing with schema validation |
+| Docker | `ms-azuretools.vscode-docker` | Docker file editing and container management |
+| Kubernetes | `ms-kubernetes-tools.vscode-kubernetes-tools` | Kubernetes manifest editing |
-Create `.vscode/settings.json` in your workspace:
+**Recommended VS Code settings for Go development:**
```json
{
- "go.toolsManagement.autoUpdate": true,
"go.useLanguageServer": true,
- "go.gopath": "",
- "go.goroot": "",
+ "go.lintOnSave": "package",
"go.lintTool": "golangci-lint",
- "go.lintFlags": [
- "--fast"
- ],
- "go.vetOnSave": "package",
"go.formatTool": "goimports",
- "go.buildOnSave": "package",
- "go.testFlags": ["-v"],
- "go.testTimeout": "30s",
+ "go.testOnSave": false,
"go.coverOnSave": false,
- "go.coverOnSingleTest": true,
- "go.coverOnSingleTestFile": true,
- "go.coverOnTestPackage": true,
"editor.formatOnSave": true,
- "editor.codeActionsOnSave": {
- "source.organizeImports": true
- },
- "files.eol": "\n",
- "yaml.schemas": {
- "https://json.schemastore.org/kustomization": [
- "kustomization.yaml",
- "kustomization.yml"
- ],
- "https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/crds/application-crd.yaml": [
- "**/argocd-apps/*.yaml",
- "**/argocd-apps/*.yml"
- ]
- },
- "kubernetes.namespace": "default",
- "kubernetes.defaultLogLevel": "info"
-}
-```
-
-Create `.vscode/launch.json` for debugging:
-
-```json
-{
- "version": "0.2.0",
- "configurations": [
- {
- "name": "Launch OpenFrame CLI",
- "type": "go",
- "request": "launch",
- "mode": "auto",
- "program": "${workspaceFolder}/main.go",
- "args": ["--help"],
- "env": {
- "GO_ENV": "development"
- }
- },
- {
- "name": "Debug Bootstrap Command",
- "type": "go",
- "request": "launch",
- "mode": "auto",
- "program": "${workspaceFolder}/main.go",
- "args": ["bootstrap", "--verbose", "--non-interactive"],
- "env": {
- "GO_ENV": "development"
- }
- },
- {
- "name": "Debug Cluster Status",
- "type": "go",
- "request": "launch",
- "mode": "auto",
- "program": "${workspaceFolder}/main.go",
- "args": ["cluster", "status"],
- "env": {
- "GO_ENV": "development"
- }
+ "[go]": {
+ "editor.defaultFormatter": "golang.go",
+ "editor.codeActionsOnSave": {
+ "source.organizeImports": "explicit"
}
- ]
+ }
}
```
-### GoLand/IntelliJ IDEA
-
-For JetBrains IDEs:
+### GoLand (JetBrains)
-#### Installation
-```bash
-# macOS
-brew install --cask goland
-
-# Or download from https://www.jetbrains.com/go/
-```
+GoLand is a fully featured Go IDE that works well with this codebase. No additional plugins are required beyond the built-in Go support.
-#### Configuration
-1. **Go Settings**: File → Settings → Go → GOROOT and GOPATH
-2. **Code Style**: File → Settings → Editor → Code Style → Go
-3. **Live Templates**: File → Settings → Editor → Live Templates
-4. **Kubernetes Plugin**: File → Settings → Plugins → Install "Kubernetes"
+---
-### Vim/Neovim
+## Go Tools Setup
-For terminal-based editing:
+Install the standard Go development tools used in this project:
-#### Installation
```bash
-# Install vim-go plugin manager
-curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
- https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
-```
-
-Add to `~/.vimrc`:
-```vim
-call plug#begin('~/.vim/plugged')
-Plug 'fatih/vim-go', { 'do': ':GoUpdateBinaries' }
-Plug 'neoclide/coc.nvim', {'branch': 'release'}
-Plug 'preservim/nerdtree'
-Plug 'airblade/vim-gitgutter'
-call plug#end()
-
-" Go-specific settings
-let g:go_fmt_command = "goimports"
-let g:go_auto_type_info = 1
-let g:go_highlight_types = 1
-let g:go_highlight_fields = 1
-let g:go_highlight_functions = 1
-let g:go_highlight_function_calls = 1
-```
-
-## Development Tools
-
-### Go Tools Installation
-
-Install essential Go development tools:
-
-```bash
-# Core Go tools
-go install golang.org/x/tools/cmd/goimports@latest
-go install golang.org/x/tools/cmd/godoc@latest
-go install golang.org/x/tools/cmd/gofmt@latest
-
-# Linting and code quality
+# Install golangci-lint (linter)
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
-go install honnef.co/go/tools/cmd/staticcheck@latest
-go install github.com/kisielk/errcheck@latest
-
-# Testing tools
-go install github.com/rakyll/gotest@latest
-go install github.com/axw/gocov/gocov@latest
-go install github.com/AlekSi/gocov-xml@latest
-
-# Documentation tools
-go install golang.org/x/tools/cmd/godoc@latest
-# Binary management
-go install github.com/cosmtrek/air@latest # Hot reload
-go install github.com/goreleaser/goreleaser@latest # Release management
-```
+# Install goimports (import formatting)
+go install golang.org/x/tools/cmd/goimports@latest
-### Configure golangci-lint
-
-Create `.golangci.yml` in the project root:
-
-```yaml
-run:
- timeout: 5m
- issues-exit-code: 1
- tests: true
-
-linters-settings:
- golint:
- min-confidence: 0
- gocyclo:
- min-complexity: 15
- goimports:
- local-prefixes: github.com/flamingo-stack/openframe-cli
- govet:
- check-shadowing: true
- errcheck:
- check-type-assertions: true
- check-blank: true
- unused:
- check-exported: false
-
-linters:
- enable:
- - bodyclose
- - deadcode
- - depguard
- - dogsled
- - dupl
- - errcheck
- - exportloopref
- - exhaustive
- - goconst
- - gocritic
- - gofmt
- - goimports
- - golint
- - goprintffuncname
- - gosec
- - gosimple
- - govet
- - ineffassign
- - misspell
- - nakedret
- - noctx
- - nolintlint
- - rowserrcheck
- - staticcheck
- - structcheck
- - stylecheck
- - typecheck
- - unconvert
- - unparam
- - unused
- - varcheck
- - whitespace
-
-issues:
- exclude-rules:
- - path: _test\.go
- linters:
- - gosec
- - dupl
- exclude-use-default: false
- exclude:
- - "Error return value of .((os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*print.*|os\.(Un)?Setenv). is not checked"
+# Install govulncheck (vulnerability scanner)
+go install golang.org/x/vuln/cmd/govulncheck@latest
```
-### Shell Configuration
-
-Add helpful aliases and functions to your shell profile:
+Verify the tools are in your `PATH`:
```bash
-# Add to ~/.bashrc, ~/.zshrc, or ~/.fish
-# OpenFrame development aliases
-alias of="go run main.go"
-alias oft="go test ./..."
-alias ofb="go build -o openframe main.go"
-alias ofl="golangci-lint run"
-
-# Go development aliases
-alias gob="go build"
-alias got="go test"
-alias gor="go run"
-alias gof="go fmt ./..."
-alias goi="goimports -w ."
-alias gol="golangci-lint run"
-
-# Kubernetes aliases for development
-alias k="kubectl"
-alias kgp="kubectl get pods"
-alias kgs="kubectl get svc"
-alias kgd="kubectl get deployment"
-alias kdp="kubectl describe pod"
-alias kl="kubectl logs"
-alias kex="kubectl exec -it"
-
-# OpenFrame specific kubectl contexts
-alias kof="kubectl config use-context k3d-openframe-local"
-alias kctx="kubectl config current-context"
-alias kns="kubectl config set-context --current --namespace"
-
-# Docker aliases
-alias d="docker"
-alias dc="docker compose"
-alias dps="docker ps"
-alias di="docker images"
-alias dl="docker logs"
-
-# Git aliases for development workflow
-alias gs="git status"
-alias ga="git add"
-alias gc="git commit"
-alias gp="git push"
-alias gl="git pull"
-alias gb="git branch"
-alias gco="git checkout"
-alias gd="git diff"
+golangci-lint version
+goimports --help
+govulncheck --help
```
-## Environment Variables
+---
-Set up development environment variables:
+## Environment Variables for Development
-```bash
-# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
+Set the following environment variables in your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) for a comfortable development experience:
-# Go development
+```bash
+# Go workspace
export GOPATH="$HOME/go"
-export GOROOT="$(go env GOROOT)"
-export PATH="$GOPATH/bin:$GOROOT/bin:$PATH"
+export PATH="$PATH:$GOPATH/bin"
-# OpenFrame CLI development
-export OPENFRAME_LOG_LEVEL="debug"
-export OPENFRAME_CONFIG_DIR="$HOME/.openframe-dev"
-export OPENFRAME_DEV_MODE="true"
+# Optional: Enable fancy logo in terminal
+export OPENFRAME_FANCY_LOGO=true
-# Kubernetes development
-export KUBECONFIG="$HOME/.kube/config"
-export KUBECTL_EXTERNAL_DIFF="diff -u"
-
-# Docker development
-export DOCKER_BUILDKIT=1
-export COMPOSE_DOCKER_CLI_BUILD=1
-
-# Development tools
-export EDITOR="code" # or vim, nano, etc.
-export BROWSER="chrome" # or firefox, safari, etc.
-
-# Testing
-export GO_TEST_TIMEOUT="30s"
-export COVERAGE_OUTPUT="coverage.out"
+# Optional: Disable color output in CI-like environments
+# export NO_COLOR=1
```
-## Kubernetes Development Setup
-
-### Configure kubectl contexts
+Apply the changes:
```bash
-# Create separate contexts for development
-kubectl config set-context openframe-dev \
- --cluster=k3d-openframe-local \
- --user=admin@k3d-openframe-local
-
-kubectl config set-context openframe-test \
- --cluster=k3d-openframe-test \
- --user=admin@k3d-openframe-test
-
-# Use development context by default
-kubectl config use-context openframe-dev
+source ~/.bashrc # or ~/.zshrc for zsh users
```
-### Install Kubernetes development tools
-
-```bash
-# Helm
-curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+---
-# K3D
-curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
+## Docker Configuration
-# Stern for log streaming
-brew install stern # macOS
-# or download from https://github.com/stern/stern/releases
+The OpenFrame CLI creates K3D clusters as Docker containers. Ensure Docker has sufficient resources:
-# kubectx and kubens for context switching
-brew install kubectx # macOS
-# or download from https://github.com/ahmetb/kubectx/releases
+### Docker Desktop (macOS / Windows)
-# K9s for cluster management
-brew install k9s # macOS
-# or download from https://github.com/derailed/k9s/releases
-```
+1. Open Docker Desktop → **Settings** → **Resources**
+2. Set **Memory** to at least **16 GB** (24 GB recommended)
+3. Set **CPUs** to at least **6** (12 recommended)
+4. Apply and Restart
-## Testing Environment Setup
+### Docker Engine (Linux)
-### Configure test databases and services
+Docker Engine on Linux uses the host system's resources directly. Ensure your machine meets the [hardware requirements](../../getting-started/prerequisites.md).
-```bash
-# Create test namespace
-kubectl create namespace openframe-test
+---
-# Install test dependencies
-helm repo add bitnami https://charts.bitnami.com/bitnami
-helm install test-redis bitnami/redis \
- --namespace openframe-test \
- --set auth.enabled=false
+## Terminal Recommendations
-# Install test monitoring
-kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/kind/deploy.yaml
-```
+The OpenFrame CLI uses rich terminal UI (pterm, promptui) that works best with a modern terminal emulator:
-### Test configuration
+| Platform | Recommended Terminal |
+|---|---|
+| macOS | iTerm2, Warp, or macOS Terminal with zsh |
+| Linux | Any xterm-256color compatible terminal (GNOME Terminal, Alacritty, Kitty) |
+| Windows | Windows Terminal + WSL2 |
-Create `test.env` for test environment variables:
+Ensure your terminal supports 256 colors:
```bash
-# Test environment configuration
-export OPENFRAME_TEST_MODE=true
-export OPENFRAME_TEST_CLUSTER="k3d-openframe-test"
-export OPENFRAME_TEST_NAMESPACE="openframe-test"
-export OPENFRAME_TEST_TIMEOUT="60s"
-
-# Test database connections
-export TEST_REDIS_URL="redis://localhost:6379"
-export TEST_DATABASE_URL="postgres://localhost:5432/openframe_test"
-
-# Integration test settings
-export INTEGRATION_TEST_ENABLED=true
-export E2E_TEST_ENABLED=false # Disable by default
+echo $TERM
+# Should output: xterm-256color or similar
```
-## Performance and Debugging Tools
-
-### Install profiling tools
-
-```bash
-# Go profiling tools
-go install github.com/google/pprof@latest
-go install github.com/uber/go-torch@latest
-
-# Memory and performance analysis
-go install github.com/pkg/profile@latest
-```
-
-### Configure debugging
-
-Add debug configuration to your project:
-
-```go
-// debug/profile.go
-// +build debug
-
-package debug
-
-import (
- "github.com/pkg/profile"
- "os"
-)
-
-func init() {
- if os.Getenv("CPUPROFILE") != "" {
- defer profile.Start().Stop()
- }
- if os.Getenv("MEMPROFILE") != "" {
- defer profile.Start(profile.MemProfile).Stop()
- }
-}
-```
+---
-## Pre-commit Hooks
+## WSL2 Setup (Windows Only)
-Set up git hooks for code quality:
+If developing on Windows, use WSL2:
```bash
-# Install pre-commit (optional but recommended)
-pip install pre-commit
-
-# Create .pre-commit-config.yaml
-cat > .pre-commit-config.yaml << 'EOF'
-repos:
- - repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v4.4.0
- hooks:
- - id: trailing-whitespace
- - id: end-of-file-fixer
- - id: check-yaml
- - id: check-added-large-files
-
- - repo: https://github.com/dnephin/pre-commit-golang
- rev: v0.5.1
- hooks:
- - id: go-fmt
- - id: go-imports
- - id: go-vet-mod
- - id: go-unit-tests-mod
- - id: golangci-lint-mod
-EOF
-
-# Install the hooks
-pre-commit install
-```
-
-Or create a simple git hook manually:
-
-```bash
-# Create .git/hooks/pre-commit
-cat > .git/hooks/pre-commit << 'EOF'
-#!/bin/bash
-# Pre-commit hook for OpenFrame CLI
-
-set -e
+# Install WSL2 (PowerShell as Administrator)
+wsl --install
-echo "Running pre-commit checks..."
+# Set WSL2 as default
+wsl --set-default-version 2
-# Format code
-echo "Running gofmt..."
-gofmt -l -w .
-
-# Organize imports
-echo "Running goimports..."
-goimports -l -w .
+# Install Ubuntu (or your preferred distro)
+wsl --install -d Ubuntu
+```
-# Run linter
-echo "Running golangci-lint..."
-golangci-lint run
+After installing WSL2, follow the Linux installation steps for Go, Docker Engine, and other tools inside your WSL2 distribution.
-# Run tests
-echo "Running tests..."
-go test -short ./...
+> The OpenFrame CLI includes built-in WSL2 support for Docker daemon detection, IP detection, and inotify limit configuration.
-echo "Pre-commit checks passed!"
-EOF
+---
-chmod +x .git/hooks/pre-commit
-```
+## Verifying Your Environment
-## Troubleshooting
+Run this checklist to confirm your development environment is ready:
-### Common Go Issues
-
-#### GOPATH/GOROOT Problems
```bash
-# Check Go environment
-go env
-
-# Reset Go environment
-go env -w GOPATH=""
-go env -w GOROOT=""
-```
+# 1. Go toolchain
+go version
-#### Module Issues
-```bash
-# Clean module cache
-go clean -modcache
+# 2. Git
+git --version
-# Reinstall dependencies
-go mod tidy
-go mod download
-```
+# 3. Docker
+docker info
-### Kubernetes Issues
+# 4. kubectl
+kubectl version --client
-#### Context Not Found
-```bash
-# List available contexts
-kubectl config get-contexts
+# 5. k3d
+k3d version
-# Create new context
-kubectl config set-context openframe-dev \
- --cluster=k3d-openframe-local \
- --user=admin@k3d-openframe-local
-```
+# 6. Helm
+helm version
-#### Tools Not Found
-```bash
-# Verify PATH includes Go bin directory
-echo $PATH | grep go
+# 7. Linting tools
+golangci-lint version
-# Add Go bin to PATH
-export PATH="$GOPATH/bin:$PATH"
+# 8. Clone and build the CLI (see Local Development guide)
```
-## Next Steps
-
-Your development environment is now ready! Continue with:
+---
-1. **[Local Development Guide](local-development.md)** - Clone and run OpenFrame CLI locally
-2. **[Architecture Overview](../architecture/README.md)** - Understand the system design
-3. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn the development workflow
-
-## Additional Resources
+## Next Steps
-- **Go Documentation**: https://golang.org/doc/
-- **Kubernetes Documentation**: https://kubernetes.io/docs/
-- **Cobra CLI Documentation**: https://cobra.dev/
-- **VS Code Go Extension**: https://marketplace.visualstudio.com/items?itemName=golang.Go
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
\ No newline at end of file
+- Proceed to [Local Development](local-development.md) to clone, build, and run the CLI from source
diff --git a/docs/development/setup/local-development.md b/docs/development/setup/local-development.md
index 66002a68..01223754 100644
--- a/docs/development/setup/local-development.md
+++ b/docs/development/setup/local-development.md
@@ -1,590 +1,308 @@
# Local Development Guide
-This guide covers cloning, building, running, and debugging OpenFrame CLI in your local development environment. Follow these steps to get the code running and start contributing.
+This guide walks you through cloning the repository, building the CLI from source, running it locally, and setting up debug configurations.
-## Prerequisites
-
-Before starting local development, ensure you have completed:
-- **[Prerequisites](../../getting-started/prerequisites.md)** - System requirements and dependencies
-- **[Environment Setup](environment.md)** - IDE, tools, and development configuration
+---
## Clone the Repository
-### Fork and Clone (Recommended for Contributors)
-
-1. **Fork the repository** on GitHub:
- - Go to https://github.com/flamingo-stack/openframe-cli
- - Click "Fork" in the top-right corner
- - Choose your GitHub account
-
-2. **Clone your fork**:
- ```bash
- # Clone your fork
- git clone https://github.com/YOUR-USERNAME/openframe-cli.git
- cd openframe-cli
-
- # Add upstream remote for syncing
- git remote add upstream https://github.com/flamingo-stack/openframe-cli.git
-
- # Verify remotes
- git remote -v
- ```
-
-### Direct Clone (Read-only)
-
-For read-only access or testing:
-
```bash
git clone https://github.com/flamingo-stack/openframe-cli.git
cd openframe-cli
```
-## Project Structure Overview
+---
-Familiarize yourself with the codebase structure:
+## Project Structure
```text
openframe-cli/
-├── main.go # Application entry point
-├── go.mod # Go module definition
-├── go.sum # Go dependency checksums
-├── cmd/ # CLI command definitions
-│ ├── root.go # Root command and version info
-│ ├── bootstrap/ # Complete environment bootstrap
-│ ├── cluster/ # Kubernetes cluster management
-│ ├── chart/ # Helm chart and ArgoCD operations
-│ └── dev/ # Development workflow tools
-├── internal/ # Private application code
-│ ├── bootstrap/ # Bootstrap orchestration service
-│ ├── cluster/ # Cluster lifecycle management
-│ ├── chart/ # Chart installation and ArgoCD integration
-│ ├── dev/ # Development tools (intercept, scaffold)
-│ └── shared/ # Common utilities and adapters
-├── tests/ # Test suites and utilities
-│ ├── integration/ # Integration tests
-│ ├── mocks/ # Test mocks and fixtures
-│ └── testutil/ # Test helper functions
-├── docs/ # Documentation
-├── examples/ # Usage examples and samples
-└── scripts/ # Build and utility scripts
-```
-
-## Build and Run
-
-### Build the Binary
-
-```bash
-# Build for your current platform
-go build -o openframe main.go
-
-# Build with version information
-VERSION=$(git describe --tags --always --dirty)
-COMMIT=$(git rev-parse --short HEAD)
-DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-go build -ldflags "-X main.version=$VERSION -X main.commit=$COMMIT -X main.date=$DATE" -o openframe main.go
-
-# Test the build
-./openframe --version
+├── main.go # Application entry point
+├── go.mod # Go module definition
+├── go.sum # Dependency lock file
+├── cmd/ # Cobra CLI command definitions
+│ ├── root.go
+│ ├── bootstrap/
+│ ├── cluster/
+│ ├── chart/
+│ └── dev/
+├── internal/ # Internal packages (not exported)
+│ ├── bootstrap/
+│ ├── cluster/
+│ ├── chart/
+│ ├── dev/
+│ └── shared/
+└── tests/ # Integration and unit test utilities
+ ├── testutil/
+ ├── integration/
+ └── mocks/
```
-### Run During Development
+---
-For rapid development cycles, run directly with Go:
+## Install Dependencies
```bash
-# Run with go run (rebuilds automatically)
-go run main.go --help
-
-# Run specific commands
-go run main.go bootstrap --help
-go run main.go cluster status
-go run main.go chart list
+go mod download
```
-### Hot Reload with Air
-
-Install and use Air for automatic rebuilds:
+Verify all modules are downloaded and tidy:
```bash
-# Install Air
-go install github.com/cosmtrek/air@latest
-
-# Create .air.toml configuration
-cat > .air.toml << 'EOF'
-root = "."
-testdata_dir = "testdata"
-tmp_dir = "tmp"
-
-[build]
-args_bin = []
-bin = "./tmp/main"
-cmd = "go build -o ./tmp/main main.go"
-delay = 1000
-exclude_dir = ["assets", "tmp", "vendor", "testdata", "docs"]
-exclude_file = []
-exclude_regex = ["_test.go"]
-exclude_unchanged = false
-follow_symlink = false
-full_bin = ""
-include_dir = []
-include_ext = ["go", "tpl", "tmpl", "html"]
-kill_delay = "0s"
-log = "build-errors.log"
-send_interrupt = false
-stop_on_root = false
-
-[color]
-app = ""
-build = "yellow"
-main = "magenta"
-runner = "green"
-watcher = "cyan"
-
-[log]
-time = false
-
-[misc]
-clean_on_exit = false
-EOF
-
-# Run with hot reload
-air
+go mod tidy
+go mod verify
```
-Now changes to Go files will automatically trigger rebuilds.
+---
-## Running Tests
+## Build the CLI
-### Unit Tests
+### Standard Build
```bash
-# Run all tests
-go test ./...
-
-# Run tests with verbose output
-go test -v ./...
-
-# Run tests with coverage
-go test -cover ./...
-
-# Generate detailed coverage report
-go test -coverprofile=coverage.out ./...
-go tool cover -html=coverage.out -o coverage.html
-open coverage.html # macOS
-# or xdg-open coverage.html # Linux
+go build -o openframe ./main.go
```
-### Integration Tests
-
-Integration tests require a running Kubernetes cluster:
+### Build with Version Information
```bash
-# Start a test cluster
-k3d cluster create openframe-test
-
-# Run integration tests
-go test -tags=integration ./tests/integration/...
-
-# Clean up
-k3d cluster delete openframe-test
+go build \
+ -ldflags="-X github.com/flamingo-stack/openframe-cli/cmd.version=dev \
+ -X github.com/flamingo-stack/openframe-cli/cmd.commit=$(git rev-parse --short HEAD) \
+ -X github.com/flamingo-stack/openframe-cli/cmd.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+ -o openframe \
+ ./main.go
```
-### Test Specific Packages
+### Verify the Build
```bash
-# Test specific packages
-go test ./internal/cluster/...
-go test ./internal/chart/...
-go test ./cmd/bootstrap/...
-
-# Test with timeout
-go test -timeout=30s ./internal/bootstrap/...
-
-# Run specific tests
-go test -run TestClusterCreate ./internal/cluster/...
-go test -run TestBootstrapService ./internal/bootstrap/...
+./openframe --help
+./openframe --version
```
-## Development Workflow
-
-### Create a Feature Branch
+---
-```bash
-# Sync with upstream (if using fork)
-git fetch upstream
-git checkout main
-git merge upstream/main
+## Running Locally
-# Create feature branch
-git checkout -b feature/your-feature-name
+You can run the CLI directly using `go run` without building a binary:
-# Or for bug fixes
-git checkout -b fix/issue-description
+```bash
+# Run with go run
+go run ./main.go --help
+go run ./main.go cluster list
+go run ./main.go bootstrap --help
```
-### Make Changes
-
-1. **Write Code**: Implement your feature or fix
-2. **Write Tests**: Add or update tests for your changes
-3. **Run Tests**: Ensure all tests pass
-4. **Format Code**: Use `gofmt` and `goimports`
-5. **Lint Code**: Run `golangci-lint`
+Or use the compiled binary:
```bash
-# Format and organize imports
-gofmt -w .
-goimports -w .
-
-# Run linter
-golangci-lint run
-
-# Run all tests
-go test ./...
+./openframe cluster list
+./openframe bootstrap my-dev-cluster --verbose
```
-### Commit Changes
+---
-Follow conventional commit format:
+## Running Commands with Verbose Output
-```bash
-# Stage changes
-git add .
-
-# Commit with descriptive message
-git commit -m "feat(cluster): add support for custom node labels"
-git commit -m "fix(bootstrap): handle timeout errors gracefully"
-git commit -m "docs(readme): update installation instructions"
+During development, always use `--verbose` / `-v` to see detailed logs:
-# Push to your fork
-git push origin feature/your-feature-name
+```bash
+./openframe bootstrap my-dev-cluster --verbose
+./openframe cluster create test-cluster --verbose
+./openframe chart install test-cluster --deployment-mode=oss-tenant --verbose
```
-## Debugging
-
-### VS Code Debugging
+---
-Use the launch configurations from [Environment Setup](environment.md):
+## Hot Reload / Watch Mode
-1. **Set breakpoints** in your code
-2. **Press F5** or go to Run → Start Debugging
-3. **Choose configuration**:
- - "Launch OpenFrame CLI" - Debug with `--help`
- - "Debug Bootstrap Command" - Debug bootstrap process
- - "Debug Cluster Status" - Debug cluster operations
+The CLI is a compiled binary — there is no native hot-reload. Use the following workflow for rapid iteration:
-### Command-line Debugging with Delve
+### Using a Watch Script
```bash
-# Install Delve
-go install github.com/go-delve/delve/cmd/dlv@latest
-
-# Debug the application
-dlv debug main.go -- bootstrap --verbose
-
-# Debug tests
-dlv test ./internal/bootstrap/
-
-# Debug with arguments
-dlv debug main.go -- cluster create --name=test-cluster
-```
-
-### Debug Commands in Delve
+# Install air (Go live reload tool)
+go install github.com/cosmtrek/air@latest
-```text
-(dlv) break main.main # Set breakpoint at main function
-(dlv) break bootstrap.go:45 # Set breakpoint at line 45 in bootstrap.go
-(dlv) continue # Continue execution
-(dlv) next # Execute next line
-(dlv) step # Step into function calls
-(dlv) print variable_name # Print variable value
-(dlv) goroutines # List all goroutines
-(dlv) exit # Exit debugger
+# Or use a simple rebuild loop in your terminal
+while true; do
+ go build -o openframe ./main.go && echo "Build OK"
+ inotifywait -r -e modify ./cmd/ ./internal/ 2>/dev/null
+done
```
-### Debugging with Print Statements
+### Manual Rebuild Pattern
-For quick debugging, add log statements:
+The most common pattern during development:
-```go
-package main
-
-import (
- "log"
- "os"
-)
-
-func debugFunction() {
- log.Printf("DEBUG: variable value: %+v", variable)
-
- // Pretty print structs
- log.Printf("DEBUG: struct: %#v", structVariable)
-
- // Print with file and line info
- log.Printf("DEBUG [%s:%d]: message", "filename.go", 123)
-}
+```bash
+go build -o openframe ./main.go && ./openframe
+```
-func init() {
- // Enable debug logging during development
- if os.Getenv("DEBUG") == "true" {
- log.SetFlags(log.LstdFlags | log.Lshortfile)
+---
+
+## Debug Configuration
+
+### VS Code — `launch.json`
+
+Add the following to `.vscode/launch.json` for debugging with VS Code:
+
+```json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Debug: bootstrap",
+ "type": "go",
+ "request": "launch",
+ "mode": "auto",
+ "program": "${workspaceFolder}/main.go",
+ "args": ["bootstrap", "--verbose"],
+ "env": {
+ "OPENFRAME_FANCY_LOGO": "false"
+ }
+ },
+ {
+ "name": "Debug: cluster create",
+ "type": "go",
+ "request": "launch",
+ "mode": "auto",
+ "program": "${workspaceFolder}/main.go",
+ "args": ["cluster", "create", "debug-cluster", "--skip-wizard"],
+ "env": {
+ "OPENFRAME_FANCY_LOGO": "false"
+ }
+ },
+ {
+ "name": "Debug: cluster list",
+ "type": "go",
+ "request": "launch",
+ "mode": "auto",
+ "program": "${workspaceFolder}/main.go",
+ "args": ["cluster", "list"]
}
+ ]
}
```
-Run with debug logging:
-```bash
-DEBUG=true go run main.go bootstrap
-```
+### GoLand
-## Testing Your Changes
+1. Create a **Run/Debug Configuration** → **Go Build**
+2. Set **Package path** to `github.com/flamingo-stack/openframe-cli`
+3. Set **Program arguments** to the command you want to debug (e.g., `bootstrap --verbose`)
+4. Add environment variables as needed
-### Manual Testing
+---
-Create test scenarios to verify your changes:
+## Running Tests During Development
```bash
-# Test bootstrap functionality
-go run main.go bootstrap --mode=oss-tenant --non-interactive
+# Run all unit tests
+go test ./...
-# Test cluster operations
-go run main.go cluster create test-cluster
-go run main.go cluster status test-cluster
-go run main.go cluster delete test-cluster
+# Run tests with verbose output
+go test -v ./...
-# Test chart operations
-go run main.go chart install test-app --repo=https://charts.example.com
-go run main.go chart list
+# Run tests for a specific package
+go test -v ./internal/cluster/...
-# Test development tools
-go run main.go dev scaffold my-service --template=microservice
-go run main.go dev intercept my-service --port=3000:8080
+# Run tests with coverage
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out
```
-### Integration Testing
-
-Test with real Kubernetes clusters:
-
-```bash
-# Create test cluster
-k3d cluster create openframe-test --agents 2
-
-# Run your changes against the cluster
-KUBECONFIG=$(k3d kubeconfig write openframe-test) go run main.go bootstrap
+See the [Testing Guide](../testing/README.md) for full details on test organization and writing new tests.
-# Verify results
-kubectl get pods --all-namespaces
-kubectl get applications -n argocd
-
-# Clean up
-k3d cluster delete openframe-test
-```
+---
-### Performance Testing
+## Linting
-Monitor resource usage and performance:
+Run the linter before submitting any changes:
```bash
-# Build optimized binary
-go build -ldflags="-s -w" -o openframe main.go
-
-# Monitor memory usage
-/usr/bin/time -v ./openframe bootstrap
-
-# Profile CPU usage
-CPUPROFILE=cpu.prof go run main.go bootstrap
-go tool pprof cpu.prof
-
-# Profile memory usage
-MEMPROFILE=mem.prof go run main.go bootstrap
-go tool pprof mem.prof
+golangci-lint run ./...
```
-## Code Quality
-
-### Automated Checks
-
-Run all quality checks before committing:
-
-```bash
-#!/bin/bash
-# quality-check.sh
-
-echo "Running code quality checks..."
+Fix formatting issues:
-# Format code
-echo "Formatting code..."
-gofmt -l -w .
-goimports -l -w .
-
-# Vet code
-echo "Vetting code..."
-go vet ./...
-
-# Run linter
-echo "Running linter..."
-golangci-lint run
-
-# Run tests
-echo "Running tests..."
-go test -race -cover ./...
-
-# Check for security issues
-echo "Checking security..."
-gosec ./...
-
-# Check dependencies
-echo "Checking dependencies..."
-go mod tidy
-go mod verify
-
-echo "All checks passed!"
-```
-
-Make it executable and run:
```bash
-chmod +x quality-check.sh
-./quality-check.sh
+gofmt -w .
+goimports -w .
```
-### Manual Code Review
-
-Before submitting changes, review:
-
-1. **Code Structure**: Is the code well-organized and follows Go conventions?
-2. **Error Handling**: Are errors properly handled and user-friendly?
-3. **Documentation**: Are public functions and packages documented?
-4. **Tests**: Are there adequate unit and integration tests?
-5. **Performance**: Are there any obvious performance issues?
-
-## Advanced Development
-
-### Working with Dependencies
+---
-```bash
-# Add a new dependency
-go get github.com/new/dependency@latest
-
-# Update dependencies
-go get -u ./...
-
-# Vendor dependencies (if needed)
-go mod vendor
-
-# Remove unused dependencies
-go mod tidy
-```
+## Working with the Mock Executor
-### Working with Build Tags
-
-Use build tags for conditional compilation:
+The CLI uses a `CommandExecutor` interface to abstract all shell command execution. During development and testing, you can use the mock executor to simulate command outputs without running real tools:
```go
-// +build debug
-
-package debug
+import "github.com/flamingo-stack/openframe-cli/internal/shared/executor"
+import "github.com/flamingo-stack/openframe-cli/tests/testutil"
-func init() {
- // Debug-only initialization
-}
-```
+// Create a mock executor
+mockExecutor := testutil.NewTestMockExecutor()
-```bash
-# Build with debug tag
-go build -tags debug -o openframe-debug main.go
+// Configure mock responses
+mockExecutor.SetResponse("k3d cluster list", &executor.CommandResult{
+ ExitCode: 0,
+ Stdout: `[{"name": "test-cluster"}]`,
+})
-# Run tests with integration tag
-go test -tags integration ./...
+// Inject into a service
+clusterService := cluster.NewClusterService(mockExecutor, true)
```
-### Cross-platform Development
-
-Build for multiple platforms:
+---
-```bash
-# Build for Linux
-GOOS=linux GOARCH=amd64 go build -o openframe-linux main.go
-
-# Build for Windows
-GOOS=windows GOARCH=amd64 go build -o openframe.exe main.go
+## Common Development Tasks
-# Build for macOS (Intel)
-GOOS=darwin GOARCH=amd64 go build -o openframe-darwin-amd64 main.go
+### Adding a New Command
-# Build for macOS (Apple Silicon)
-GOOS=darwin GOARCH=arm64 go build -o openframe-darwin-arm64 main.go
-```
+1. Create a new file under `cmd//.go`
+2. Define the Cobra command with `Use`, `Short`, `Long`, `RunE`
+3. Register the command in the parent group's `cmd//.go`
+4. Create a corresponding service in `internal//services/`
+5. Write unit tests in `internal//services/_test.go`
-## Troubleshooting
+### Adding a New Provider
-### Common Development Issues
+1. Create the provider under `internal//providers//`
+2. Implement the provider interface defined in `internal//utils/types/interfaces.go`
+3. Add the provider to the prerequisite checker if it requires external tool installation
-#### Module Problems
-```bash
-# Clear module cache
-go clean -modcache
+### Modifying Helm Values Wizard
-# Reinitialize modules
-rm go.sum
-go mod tidy
-```
+The configuration wizard is in `internal/chart/ui/configuration/wizard.go`. It coordinates:
+- `BranchConfigurator` — Git branch selection
+- `DockerConfigurator` — Docker registry settings
+- `IngressConfigurator` — Ingress/domain configuration
-#### Build Errors
-```bash
-# Clean build cache
-go clean -cache
+---
-# Rebuild everything
-go build -a main.go
-```
+## Useful Development Commands
-#### Test Failures
```bash
-# Run tests with verbose output
-go test -v -race ./...
+# Check for vulnerabilities
+govulncheck ./...
-# Run specific failing test
-go test -v -run TestSpecificFunction ./path/to/package
-```
+# List all available CLI commands
+./openframe --help
-#### Kubernetes Context Issues
-```bash
-# Check current context
-kubectl config current-context
+# Dry-run a cluster create (no actual cluster created)
+./openframe cluster create test --dry-run
-# Switch to correct context
-kubectl config use-context k3d-openframe-local
+# Dry-run a chart install
+./openframe chart install my-cluster --dry-run
-# Verify cluster connectivity
-kubectl cluster-info
+# Build integration test binary
+go test -c ./tests/integration/... -o /tmp/openframe-integration-tests
```
-### Debug Environment Variables
-
-Set these for debugging:
-
-```bash
-export GODEBUG="gctrace=1" # GC tracing
-export GOTRACEBACK="all" # Full stack traces
-export OPENFRAME_LOG_LEVEL="debug" # Detailed logging
-export KUBECONFIG="$HOME/.kube/config"
-```
+---
## Next Steps
-Now that you have a working development environment:
-
-1. **[Architecture Overview](../architecture/README.md)** - Understand the system design
-2. **[Contributing Guidelines](../contributing/guidelines.md)** - Learn the contribution process
-3. **[Testing Guide](../testing/README.md)** - Deep dive into testing strategies
-
-## Getting Help
-
-If you encounter issues:
-
-- **Check existing issues**: Search GitHub issues for similar problems
-- **Ask in Slack**: Join the [OpenMSP community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
-- **Review documentation**: Check other guides in this repository
-- **Debug systematically**: Use logging and debugging tools to isolate issues
-
-Happy coding! 🚀
\ No newline at end of file
+- Review the [Architecture Overview](../architecture/README.md) to understand how components fit together
+- Read the [Contributing Guidelines](../contributing/guidelines.md) before opening a pull request
diff --git a/docs/development/testing/README.md b/docs/development/testing/README.md
new file mode 100644
index 00000000..4ea52886
--- /dev/null
+++ b/docs/development/testing/README.md
@@ -0,0 +1,318 @@
+# Testing Guide
+
+OpenFrame CLI has a layered testing strategy: unit tests with mock executors for fast, isolated testing, and integration tests that exercise the real CLI binary against actual K3D infrastructure.
+
+---
+
+## Test Structure and Organization
+
+```text
+tests/
+├── testutil/ # Shared test utilities (used by all test types)
+│ ├── setup.go # Flag factories, mock setup, test initialization
+│ ├── assertions.go # Custom assertion helpers
+│ ├── cluster.go # Cluster-specific test utilities
+│ ├── patterns.go # Common test patterns
+│ └── utilities.go # General test utilities
+├── integration/ # End-to-end CLI integration tests
+│ └── common/
+│ ├── cli_runner.go # CLI binary builder and runner
+│ ├── cluster_management.go # Cluster lifecycle test helpers
+│ └── dependencies.go # Integration test dependency checks
+└── mocks/
+ └── dev/
+ └── kubernetes.go # Kubernetes mock implementations
+```
+
+Unit tests live alongside the source code they test:
+
+```text
+internal/
+├── cluster/
+│ ├── service.go
+│ └── service_test.go # Unit tests for ClusterService
+├── chart/
+│ └── services/
+│ ├── chart_service.go
+│ └── chart_service_test.go # Unit tests for ChartService
+└── shared/
+ └── executor/
+ ├── executor.go
+ └── executor_test.go # Unit tests for executor
+```
+
+---
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+go test ./...
+```
+
+### Run with Verbose Output
+
+```bash
+go test -v ./...
+```
+
+### Run a Specific Package
+
+```bash
+go test -v ./internal/cluster/...
+go test -v ./internal/chart/...
+go test -v ./internal/dev/...
+go test -v ./internal/shared/...
+```
+
+### Run a Specific Test
+
+```bash
+go test -v -run TestClusterCreate ./internal/cluster/...
+go test -v -run TestBootstrapService ./internal/bootstrap/...
+```
+
+### Run Tests with Coverage
+
+```bash
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out -o coverage.html
+open coverage.html # macOS
+xdg-open coverage.html # Linux
+```
+
+### Run Integration Tests
+
+> Integration tests require Docker and k3d to be installed and running.
+
+```bash
+go test -v -tags integration ./tests/integration/...
+```
+
+---
+
+## Test Types
+
+### Unit Tests (Fast, No External Dependencies)
+
+Unit tests use the `MockCommandExecutor` to simulate all external tool calls without actually running Docker, k3d, or Helm. They are fast and can run anywhere.
+
+```go
+import (
+ "testing"
+ "github.com/flamingo-stack/openframe-cli/tests/testutil"
+)
+
+func TestClusterCreate(t *testing.T) {
+ // Initialize test mode (disables interactive UI)
+ testutil.InitializeTestMode()
+
+ // Create mock-based test flags
+ flags := testutil.CreateStandardTestFlags()
+ testutil.SetVerboseMode(flags, false)
+
+ // Run the operation under test
+ // Mock executor returns pre-configured responses
+ result, err := flags.ClusterService.ListClusters(context.Background())
+
+ // Assert using testify
+ require.NoError(t, err)
+ assert.Empty(t, result)
+}
+```
+
+### Integration Tests (Real K3D, Docker Required)
+
+Integration tests build the CLI binary and run it as a subprocess, capturing stdout/stderr/exit codes:
+
+```go
+import (
+ "testing"
+ "github.com/flamingo-stack/openframe-cli/tests/integration/common"
+)
+
+func TestMain(m *testing.M) {
+ if err := common.InitializeCLI(); err != nil {
+ log.Fatal("Failed to build CLI:", err)
+ }
+ defer common.CleanupCLI()
+ os.Exit(m.Run())
+}
+
+func TestClusterListCommand(t *testing.T) {
+ result := common.RunCLI("cluster", "list")
+
+ if !result.Success() {
+ t.Fatalf("cluster list failed: %s", result.ErrorMessage())
+ }
+
+ assert.Contains(t, result.Stdout, "NAME")
+}
+```
+
+---
+
+## Writing New Tests
+
+### Setting Up a Unit Test
+
+Use `testutil.CreateStandardTestFlags()` to get a fully configured test environment with mock responses:
+
+```go
+func TestMyNewFeature(t *testing.T) {
+ testutil.InitializeTestMode()
+ flags := testutil.CreateStandardTestFlags()
+
+ // Customize mock responses if needed
+ flags.MockExecutor.SetResponse("k3d cluster create my-cluster", &executor.CommandResult{
+ ExitCode: 0,
+ Stdout: "INFO[0000] Cluster 'my-cluster' created successfully!",
+ })
+
+ // Exercise your code
+ err := someService.DoOperation(context.Background(), flags)
+ assert.NoError(t, err)
+}
+```
+
+### Testing Error Conditions
+
+```go
+func TestClusterCreateFailure(t *testing.T) {
+ testutil.InitializeTestMode()
+ flags := testutil.CreateStandardTestFlags()
+
+ // Simulate a tool failure
+ flags.MockExecutor.SetResponse("k3d cluster create bad-name", &executor.CommandResult{
+ ExitCode: 1,
+ Stderr: "Error: cluster name 'bad-name' is invalid",
+ })
+
+ err := clusterService.CreateCluster(context.Background(), badConfig)
+ assert.Error(t, err)
+ assert.True(t, errors.IsCommandError(err))
+}
+```
+
+### Testing the Configuration Wizard
+
+The wizard uses interactive prompts (`promptui`). In tests, initialize test mode to disable interactive elements:
+
+```go
+func TestWizardNonInteractive(t *testing.T) {
+ testutil.InitializeTestMode() // Disables all prompts
+ // ...
+}
+```
+
+### Testing Validation
+
+```go
+func TestValidateClusterName(t *testing.T) {
+ testCases := []struct {
+ name string
+ input string
+ wantErr bool
+ }{
+ {"valid name", "my-cluster", false},
+ {"with numbers", "cluster-01", false},
+ {"empty name", "", true},
+ {"spaces not allowed", "my cluster", true},
+ {"too long", strings.Repeat("a", 64), true},
+ }
+
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ err := models.ValidateClusterName(tc.input)
+ if tc.wantErr {
+ assert.Error(t, err)
+ } else {
+ assert.NoError(t, err)
+ }
+ })
+ }
+}
+```
+
+---
+
+## Mock Executor
+
+The `MockCommandExecutor` is the foundation of unit testing in OpenFrame CLI. It implements the `CommandExecutor` interface and returns pre-configured responses:
+
+```go
+// Create a new mock executor
+executor := testutil.NewTestMockExecutor()
+
+// Set a custom response for a specific command
+executor.SetResponse("k3d cluster list --output json", &executor.CommandResult{
+ ExitCode: 0,
+ Stdout: `[{"name":"test-cluster","nodes":[]}]`,
+})
+
+// The mock records all commands executed — useful for assertions
+calledCommands := executor.GetCalledCommands()
+assert.Contains(t, calledCommands, "k3d cluster list --output json")
+```
+
+---
+
+## Test Utilities Reference
+
+| Function | Package | Purpose |
+|---|---|---|
+| `InitializeTestMode()` | `testutil` | Disables interactive UI elements (prompts, spinners) |
+| `NewTestMockExecutor()` | `testutil` | Creates a new `MockCommandExecutor` |
+| `CreateStandardTestFlags()` | `testutil` | Creates unit test environment with mocked k3d responses |
+| `CreateIntegrationTestFlags()` | `testutil` | Creates real dependency container for integration tests |
+| `SetVerboseMode(flags, bool)` | `testutil` | Configures verbose logging on a test flag container |
+| `InitializeCLI()` | `integration/common` | Builds the CLI binary (cached by source timestamp) |
+| `CleanupCLI()` | `integration/common` | Removes the test CLI binary |
+| `RunCLI(args...)` | `integration/common` | Executes a CLI command and captures output |
+
+---
+
+## Coverage Requirements
+
+The project aims for the following coverage targets:
+
+| Package | Target Coverage |
+|---|---|
+| `internal/cluster/` | 80%+ |
+| `internal/chart/` | 75%+ |
+| `internal/dev/` | 70%+ |
+| `internal/shared/` | 85%+ |
+| `cmd/` | 60%+ (primarily tested via integration) |
+
+Check current coverage:
+
+```bash
+go test -coverprofile=coverage.out ./...
+go tool cover -func=coverage.out | grep -E "total|internal"
+```
+
+---
+
+## CI Test Execution
+
+In CI/CD environments, the prerequisite checker automatically detects CI and skips interactive prompts. Unit tests run in all CI environments. Integration tests require Docker and k3d to be available in the CI runner.
+
+```bash
+# Unit tests only (no Docker/k3d required)
+go test ./internal/... ./cmd/...
+
+# Full test suite including integration
+go test ./... -tags integration
+```
+
+---
+
+## Troubleshooting Tests
+
+| Issue | Cause | Fix |
+|---|---|---|
+| Prompts blocking in tests | Test mode not initialized | Call `testutil.InitializeTestMode()` at the start of tests |
+| Mock responses not matching | Command string doesn't match exactly | Print `executor.GetCalledCommands()` to see actual strings used |
+| Integration test binary not found | CLI not built | Call `common.InitializeCLI()` in `TestMain` |
+| Flaky integration tests | Race conditions in cluster operations | Add appropriate timeouts and retries using test utilities |
diff --git a/docs/diagrams/architecture/README.md b/docs/diagrams/architecture/README.md
index 7b3e892e..6c237ada 100644
--- a/docs/diagrams/architecture/README.md
+++ b/docs/diagrams/architecture/README.md
@@ -4,10 +4,11 @@ This directory contains Mermaid diagrams generated from architecture analysis.
## Diagrams
-- **[High-Level System Design](./high-level-system-design.mmd)** - `.mmd` file
-- **[Dependency Flow Between Modules](./dependency-flow-between-modules.mmd)** - `.mmd` file
-- **[Complete Bootstrap Workflow](./complete-bootstrap-workflow.mmd)** - `.mmd` file
-- **[Development Intercept Workflow](./development-intercept-workflow.mmd)** - `.mmd` file
+- **[High-Level Architecture Diagram](./high-level-architecture-diagram.mmd)** - `.mmd` file
+- **[Dependency Graph](./dependency-graph.mmd)** - `.mmd` file
+- **[Bootstrap Command Sequence](./bootstrap-command-sequence.mmd)** - `.mmd` file
+- **[Chart Install Interactive Configuration Flow](./chart-install-interactive-configuration-flow.mmd)** - `.mmd` file
+- **[How Dependencies Are Used](./how-dependencies-are-used.mmd)** - `.mmd` file
## Viewing Diagrams
diff --git a/docs/diagrams/architecture/bootstrap-command-sequence.mmd b/docs/diagrams/architecture/bootstrap-command-sequence.mmd
new file mode 100644
index 00000000..5502da54
--- /dev/null
+++ b/docs/diagrams/architecture/bootstrap-command-sequence.mmd
@@ -0,0 +1,42 @@
+sequenceDiagram
+ participant User
+ participant CLI as "openframe bootstrap"
+ participant Bootstrap as "bootstrap.Service"
+ participant ClusterSvc as "cluster.ClusterService"
+ participant K3dMgr as "k3d.Manager"
+ participant ChartSvc as "chart.ChartService"
+ participant HelmMgr as "helm.HelmManager"
+ participant ArgoCDMgr as "argocd.Manager"
+ participant GitRepo as "git.Repository"
+
+ User->>CLI: openframe bootstrap [cluster-name]
+ CLI->>Bootstrap: Execute(cmd, args)
+ Bootstrap->>Bootstrap: Validate flags (mode, non-interactive)
+
+ Bootstrap->>ClusterSvc: CreateClusterWithPrerequisitesNonInteractive()
+ ClusterSvc->>ClusterSvc: CheckPrerequisites (Docker, k3d, kubectl, helm)
+ ClusterSvc->>K3dMgr: CreateCluster(config)
+ K3dMgr->>K3dMgr: createK3dConfigFile()
+ K3dMgr-->>ClusterSvc: *rest.Config
+ ClusterSvc-->>Bootstrap: *rest.Config
+
+ Bootstrap->>ChartSvc: InstallChartsWithConfig(request)
+ ChartSvc->>ChartSvc: CheckPrerequisites (git, helm, mkcert)
+ ChartSvc->>ChartSvc: ConfigureHelmValues (wizard or non-interactive)
+
+ ChartSvc->>HelmMgr: InstallArgoCDWithProgress(ctx, config)
+ HelmMgr-->>ChartSvc: ArgoCD installed
+
+ ChartSvc->>GitRepo: CloneChartRepository(appOfAppsConfig)
+ GitRepo-->>ChartSvc: CloneResult (tempDir, chartPath)
+
+ ChartSvc->>HelmMgr: InstallAppOfAppsFromLocal(ctx, config, certFile, keyFile)
+ HelmMgr-->>ChartSvc: app-of-apps installed
+
+ ChartSvc->>ArgoCDMgr: WaitForApplications(ctx, config)
+ ArgoCDMgr->>ArgoCDMgr: Poll ArgoCD Application CRDs
+ ArgoCDMgr-->>ChartSvc: All apps Healthy + Synced
+
+ ChartSvc-->>Bootstrap: nil (success)
+ Bootstrap-->>CLI: nil
+ CLI-->>User: Bootstrap complete
diff --git a/docs/diagrams/architecture/chart-install-interactive-configuration-flow.mmd b/docs/diagrams/architecture/chart-install-interactive-configuration-flow.mmd
new file mode 100644
index 00000000..f24bbc7e
--- /dev/null
+++ b/docs/diagrams/architecture/chart-install-interactive-configuration-flow.mmd
@@ -0,0 +1,33 @@
+sequenceDiagram
+ participant User
+ participant Workflow as "InstallationWorkflow"
+ participant Wizard as "ConfigurationWizard"
+ participant Modifier as "HelmValuesModifier"
+ participant Builder as "config.Builder"
+ participant Installer as "chart.Installer"
+
+ User->>Workflow: ExecuteWithContext(ctx, req)
+ Workflow->>Workflow: SelectCluster (interactive or arg)
+ Workflow->>Wizard: ConfigureHelmValues()
+ Wizard->>User: Select deployment mode (OSS/SaaS/SaaS-Shared)
+ User-->>Wizard: oss-tenant
+ Wizard->>User: Select config mode (default/interactive)
+ User-->>Wizard: interactive
+ Wizard->>Modifier: LoadOrCreateBaseValues()
+ Modifier-->>Wizard: map[string]interface{}
+ Wizard->>User: Configure branch / Docker / Ingress
+ User-->>Wizard: selections
+ Wizard->>Modifier: ApplyConfiguration(values, config)
+ Wizard->>Modifier: CreateTemporaryValuesFile(values)
+ Modifier-->>Wizard: helm-values-tmp.yaml
+ Wizard-->>Workflow: ChartConfiguration
+
+ Workflow->>Builder: BuildInstallConfig(...)
+ Builder->>Builder: getBranchFromHelmValues()
+ Builder-->>Workflow: ChartInstallConfig
+
+ Workflow->>Installer: InstallChartsWithContext(ctx, config)
+ Installer->>Installer: ArgoCD install
+ Installer->>Installer: app-of-apps install
+ Installer->>Installer: WaitForApplications
+ Installer-->>Workflow: success
diff --git a/docs/diagrams/architecture/complete-bootstrap-workflow.mmd b/docs/diagrams/architecture/complete-bootstrap-workflow.mmd
deleted file mode 100644
index 366b0980..00000000
--- a/docs/diagrams/architecture/complete-bootstrap-workflow.mmd
+++ /dev/null
@@ -1,32 +0,0 @@
-sequenceDiagram
- participant User
- participant Bootstrap as Bootstrap Service
- participant Cluster as Cluster Service
- participant K3D as K3D Provider
- participant Chart as Chart Service
- participant Helm as Helm Provider
- participant ArgoCD as ArgoCD Provider
- participant K8s as Kubernetes API
-
- User->>Bootstrap: openframe bootstrap
- Bootstrap->>Bootstrap: Check prerequisites
- Bootstrap->>Cluster: Create cluster
- Cluster->>K3D: Create K3D cluster
- K3D->>K8s: Initialize cluster
- K8s-->>K3D: Cluster ready
- K3D-->>Cluster: Cluster config
- Cluster-->>Bootstrap: rest.Config
-
- Bootstrap->>Chart: Install charts
- Chart->>Helm: Install ArgoCD
- Helm->>K8s: Deploy ArgoCD
- K8s-->>Helm: ArgoCD running
- Helm-->>Chart: Installation complete
-
- Chart->>ArgoCD: Install app-of-apps
- ArgoCD->>K8s: Create Application CRDs
- K8s-->>ArgoCD: Applications created
- ArgoCD->>ArgoCD: Sync applications
- ArgoCD-->>Chart: Applications synced
- Chart-->>Bootstrap: Charts installed
- Bootstrap-->>User: Environment ready
diff --git a/docs/diagrams/architecture/dependency-flow-between-modules.mmd b/docs/diagrams/architecture/dependency-flow-between-modules.mmd
deleted file mode 100644
index 4141f827..00000000
--- a/docs/diagrams/architecture/dependency-flow-between-modules.mmd
+++ /dev/null
@@ -1,76 +0,0 @@
-graph TD
- subgraph "Command Layer"
- RootCmd[Root Command]
- BootstrapCmd[Bootstrap Command]
- ClusterCmd[Cluster Commands]
- ChartCmd[Chart Commands]
- DevCmd[Dev Commands]
- end
-
- subgraph "Service Orchestration"
- BootstrapSvc[Bootstrap Service]
- end
-
- subgraph "Domain Services"
- ClusterSvc[Cluster Service]
- ChartSvc[Chart Service]
- InterceptSvc[Intercept Service]
- ScaffoldSvc[Scaffold Service]
- end
-
- subgraph "Provider Implementations"
- K3DMgr[K3D Manager]
- HelmMgr[Helm Manager]
- ArgoCDMgr[ArgoCD Manager]
- TelepresenceProv[Telepresence Provider]
- KubectlProv[Kubectl Provider]
- GitRepo[Git Repository]
- end
-
- subgraph "Shared Infrastructure"
- Executor[Command Executor]
- UI[UI Components]
- Config[Configuration]
- Prerequisites[Prerequisites]
- end
-
- RootCmd --> BootstrapCmd
- RootCmd --> ClusterCmd
- RootCmd --> ChartCmd
- RootCmd --> DevCmd
-
- BootstrapCmd --> BootstrapSvc
- ClusterCmd --> ClusterSvc
- ChartCmd --> ChartSvc
- DevCmd --> InterceptSvc
- DevCmd --> ScaffoldSvc
-
- BootstrapSvc --> ClusterSvc
- BootstrapSvc --> ChartSvc
-
- ClusterSvc --> K3DMgr
- ChartSvc --> HelmMgr
- ChartSvc --> ArgoCDMgr
- ChartSvc --> GitRepo
- InterceptSvc --> TelepresenceProv
- InterceptSvc --> KubectlProv
- ScaffoldSvc --> KubectlProv
-
- K3DMgr --> Executor
- HelmMgr --> Executor
- ArgoCDMgr --> Executor
- TelepresenceProv --> Executor
- KubectlProv --> Executor
- GitRepo --> Executor
-
- ClusterSvc --> UI
- ChartSvc --> UI
- InterceptSvc --> UI
- ScaffoldSvc --> UI
-
- ClusterSvc --> Config
- ChartSvc --> Config
-
- ClusterSvc --> Prerequisites
- ChartSvc --> Prerequisites
- DevCmd --> Prerequisites
diff --git a/docs/diagrams/architecture/dependency-graph.mmd b/docs/diagrams/architecture/dependency-graph.mmd
new file mode 100644
index 00000000..14742f78
--- /dev/null
+++ b/docs/diagrams/architecture/dependency-graph.mmd
@@ -0,0 +1,75 @@
+graph LR
+ subgraph Commands["cmd/"]
+ RC["root.go"]
+ BC["bootstrap"]
+ CC["cluster/*"]
+ CHC["chart/*"]
+ DC["dev/*"]
+ end
+
+ subgraph Services["internal/*/services"]
+ BS["bootstrap.Service"]
+ CS["cluster.ClusterService"]
+ CHS["chart.ChartService"]
+ IS["intercept.Service"]
+ SS["scaffold.Service"]
+ end
+
+ subgraph Providers["internal/*/providers"]
+ K3DP["k3d.Manager"]
+ HP["helm.HelmManager"]
+ AP["argocd.Manager"]
+ GP["git.Repository"]
+ KP["kubectl.Provider"]
+ TP["telepresence.Provider"]
+ end
+
+ subgraph SharedInfra["internal/shared/"]
+ EX["executor"]
+ ERR["errors"]
+ UIL["ui"]
+ CFG["config"]
+ end
+
+ RC --> BC
+ RC --> CC
+ RC --> CHC
+ RC --> DC
+
+ BC --> BS
+ CC --> CS
+ CHC --> CHS
+ DC --> IS
+ DC --> SS
+
+ BS --> CS
+ BS --> CHS
+
+ CS --> K3DP
+ CHS --> HP
+ CHS --> AP
+ CHS --> GP
+ IS --> KP
+ IS --> TP
+ SS --> KP
+ SS --> CHS
+
+ K3DP --> EX
+ HP --> EX
+ AP --> EX
+ GP --> EX
+ KP --> EX
+ TP --> EX
+
+ CS --> ERR
+ CHS --> ERR
+ IS --> ERR
+
+ CS --> UIL
+ CHS --> UIL
+ IS --> UIL
+ SS --> UIL
+
+ HP --> CFG
+ AP --> CFG
+ K3DP --> CFG
diff --git a/docs/diagrams/architecture/development-intercept-workflow.mmd b/docs/diagrams/architecture/development-intercept-workflow.mmd
deleted file mode 100644
index ec78ee72..00000000
--- a/docs/diagrams/architecture/development-intercept-workflow.mmd
+++ /dev/null
@@ -1,30 +0,0 @@
-sequenceDiagram
- participant Dev as Developer
- participant Intercept as Intercept Service
- participant Kubectl as Kubectl Provider
- participant Telepresence as Telepresence Provider
- participant K8s as Kubernetes
- participant Local as Local Development
-
- Dev->>Intercept: openframe dev intercept
- Intercept->>Kubectl: Get services
- Kubectl->>K8s: List services
- K8s-->>Kubectl: Service list
- Kubectl-->>Intercept: Available services
- Intercept->>Dev: Select service/port
- Dev->>Intercept: Service selection
-
- Intercept->>Telepresence: Setup intercept
- Telepresence->>K8s: Create intercept
- K8s->>Telepresence: Traffic routing active
- Telepresence->>Local: Forward traffic
- Local->>Dev: Local debugging
-
- Note over Dev,Local: Development session active
-
- Dev->>Intercept: Stop intercept (Ctrl+C)
- Intercept->>Telepresence: Cleanup intercept
- Telepresence->>K8s: Remove routing
- K8s-->>Telepresence: Cleanup complete
- Telepresence-->>Intercept: Disconnected
- Intercept-->>Dev: Session ended
diff --git a/docs/diagrams/architecture/high-level-architecture-diagram.mmd b/docs/diagrams/architecture/high-level-architecture-diagram.mmd
new file mode 100644
index 00000000..314c1d5c
--- /dev/null
+++ b/docs/diagrams/architecture/high-level-architecture-diagram.mmd
@@ -0,0 +1,88 @@
+graph TB
+ subgraph CLI["CLI Layer (cmd/)"]
+ Root["root.go"]
+ BootstrapCmd["bootstrap"]
+ ClusterCmd["cluster"]
+ ChartCmd["chart"]
+ DevCmd["dev"]
+ end
+
+ subgraph Internal["Internal Services (internal/)"]
+ BootstrapSvc["bootstrap/service.go"]
+ ClusterSvc["cluster/service.go"]
+ ChartSvc["chart/services/"]
+ DevSvc["dev/services/"]
+ end
+
+ subgraph Providers["Providers"]
+ K3dProvider["cluster/providers/k3d"]
+ HelmProvider["chart/providers/helm"]
+ ArgoCDProvider["chart/providers/argocd"]
+ GitProvider["chart/providers/git"]
+ KubectlProvider["dev/providers/kubectl"]
+ TelepresenceProvider["dev/providers/telepresence"]
+ end
+
+ subgraph External["External Tools"]
+ K3D["K3D"]
+ Helm["Helm"]
+ ArgoCD["ArgoCD"]
+ Git["Git"]
+ Telepresence["Telepresence"]
+ Skaffold["Skaffold"]
+ Docker["Docker"]
+ Kubectl["kubectl"]
+ end
+
+ subgraph Shared["Shared Infrastructure (internal/shared/)"]
+ Executor["executor"]
+ Errors["errors"]
+ UI["ui"]
+ Config["config"]
+ Files["files"]
+ Flags["flags"]
+ end
+
+ subgraph Target["Target Environment"]
+ K8s["Kubernetes Cluster"]
+ Apps["ArgoCD Applications"]
+ Services["Microservices"]
+ end
+
+ Root --> BootstrapCmd
+ Root --> ClusterCmd
+ Root --> ChartCmd
+ Root --> DevCmd
+
+ BootstrapCmd --> BootstrapSvc
+ ClusterCmd --> ClusterSvc
+ ChartCmd --> ChartSvc
+ DevCmd --> DevSvc
+
+ BootstrapSvc --> ClusterSvc
+ BootstrapSvc --> ChartSvc
+
+ ClusterSvc --> K3dProvider
+ ChartSvc --> HelmProvider
+ ChartSvc --> ArgoCDProvider
+ ChartSvc --> GitProvider
+ DevSvc --> KubectlProvider
+ DevSvc --> TelepresenceProvider
+
+ K3dProvider --> K3D
+ HelmProvider --> Helm
+ ArgoCDProvider --> ArgoCD
+ GitProvider --> Git
+ TelepresenceProvider --> Telepresence
+ DevSvc --> Skaffold
+ K3dProvider --> Docker
+ KubectlProvider --> Kubectl
+
+ K3D --> K8s
+ Helm --> Apps
+ ArgoCD --> Apps
+ Telepresence --> Services
+
+ ClusterSvc --> Shared
+ ChartSvc --> Shared
+ DevSvc --> Shared
diff --git a/docs/diagrams/architecture/high-level-system-design.mmd b/docs/diagrams/architecture/high-level-system-design.mmd
deleted file mode 100644
index 7f3080f4..00000000
--- a/docs/diagrams/architecture/high-level-system-design.mmd
+++ /dev/null
@@ -1,56 +0,0 @@
-graph TB
- subgraph "CLI Layer"
- Root[Root Command]
- Bootstrap[Bootstrap Command]
- Cluster[Cluster Commands]
- Chart[Chart Commands]
- Dev[Dev Commands]
- end
-
- subgraph "Service Layer"
- ClusterSvc[Cluster Service]
- ChartSvc[Chart Service]
- InterceptSvc[Intercept Service]
- ScaffoldSvc[Scaffold Service]
- end
-
- subgraph "Provider Layer"
- K3D[K3D Provider]
- Helm[Helm Provider]
- ArgoCD[ArgoCD Provider]
- Telepresence[Telepresence Provider]
- Kubectl[Kubectl Provider]
- end
-
- subgraph "External Systems"
- Docker[Docker]
- K8s[Kubernetes]
- Git[Git Repositories]
- Registry[Container Registry]
- end
-
- Root --> Bootstrap
- Root --> Cluster
- Root --> Chart
- Root --> Dev
-
- Bootstrap --> ClusterSvc
- Bootstrap --> ChartSvc
- Cluster --> ClusterSvc
- Chart --> ChartSvc
- Dev --> InterceptSvc
- Dev --> ScaffoldSvc
-
- ClusterSvc --> K3D
- ChartSvc --> Helm
- ChartSvc --> ArgoCD
- InterceptSvc --> Telepresence
- InterceptSvc --> Kubectl
- ScaffoldSvc --> Kubectl
-
- K3D --> Docker
- Helm --> K8s
- ArgoCD --> K8s
- ArgoCD --> Git
- Telepresence --> K8s
- Kubectl --> K8s
diff --git a/docs/diagrams/architecture/how-dependencies-are-used.mmd b/docs/diagrams/architecture/how-dependencies-are-used.mmd
new file mode 100644
index 00000000..d85d312c
--- /dev/null
+++ b/docs/diagrams/architecture/how-dependencies-are-used.mmd
@@ -0,0 +1,20 @@
+graph TD
+ CLI["OpenFrame CLI"] --> cobra["cobra\n(command routing)"]
+ CLI --> pterm["pterm\n(all terminal UI)"]
+ CLI --> promptui["promptui\n(select menus, text input)"]
+
+ ChartSvc["Chart Services"] --> clientgo["client-go\n(K8s API)"]
+ ChartSvc --> argocdclient["argo-cd client\n(application watch)"]
+ ChartSvc --> apiext["apiextensions\n(CRD checks)"]
+ ChartSvc --> dynamic["dynamic client\n(resource ops)"]
+ ChartSvc --> yamlsigs["sigs.k8s.io/yaml\n(K8s YAML)"]
+ ChartSvc --> yamlv3["gopkg.in/yaml.v3\n(helm values)"]
+
+ ClusterSvc["Cluster Service"] --> clientgo
+ ClusterSvc --> clientcmd["clientcmd\n(kubeconfig)"]
+
+ SharedUI["shared/ui"] --> pterm
+ SharedUI["shared/ui"] --> promptui
+ SharedUI["shared/ui"] --> term["golang.org/x/term\n(raw terminal)"]
+
+ Tests["Tests"] --> testify["testify\n(assertions)"]
diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md
index 24c144d6..dc09fb99 100644
--- a/docs/getting-started/first-steps.md
+++ b/docs/getting-started/first-steps.md
@@ -1,467 +1,220 @@
-# First Steps with OpenFrame CLI
+# First Steps
-Now that you have OpenFrame CLI installed and your first environment bootstrapped, let's explore the key features and workflows. This guide covers the essential first steps to get you productive with OpenFrame.
+You've successfully bootstrapped your first OpenFrame environment. Here are the first 5 things to do to get comfortable with your new cluster and start using OpenFrame effectively.
-## Your First 5 Actions
+---
-### 1. Explore the CLI Structure
+## 1. Check Your Cluster Status
-Get familiar with the command hierarchy:
+After bootstrap, verify everything is healthy:
```bash
-# See all available commands
-openframe --help
-
-# Explore each command group
-openframe cluster --help
-openframe chart --help
-openframe dev --help
-openframe bootstrap --help
+openframe cluster status my-openframe
```
-The CLI is organized into logical groups:
-- **bootstrap**: One-time environment setup
-- **cluster**: Kubernetes cluster lifecycle
-- **chart**: Application and service deployment
-- **dev**: Development and debugging tools
-
-### 2. Check Your Environment Status
-
-Verify everything is running correctly:
+Use the `--detailed` flag for full node and application information:
```bash
-# Overall cluster health
-openframe cluster status
-
-# List all running clusters
-openframe cluster list
-
-# Check installed charts and applications
-openframe chart list
+openframe cluster status my-openframe --detailed
```
-Expected healthy output:
-```text
-📊 Cluster Status: openframe-local
-✅ Cluster is running
-✅ ArgoCD is healthy
-✅ All core services operational
-```
+This will display:
-### 3. Access the ArgoCD Dashboard
+- Cluster health and node count
+- Running Kubernetes nodes
+- ArgoCD application sync/health status for all deployed apps
-ArgoCD provides a web interface for GitOps deployments:
+To see a quick list of all managed clusters:
```bash
-# Get admin password
-kubectl -n argocd get secret argocd-initial-admin-secret \
- -o jsonpath="{.data.password}" | base64 -d; echo
-
-# Port forward to access UI
-kubectl port-forward svc/argocd-server -n argocd 8080:443
-
-# Open in browser: https://localhost:8080
-# Username: admin
-# Password: (from command above)
+openframe cluster list
```
-In the ArgoCD UI, you'll see:
-- **Applications**: Deployed services and components
-- **Repositories**: Connected Git repositories
-- **Settings**: Configuration and policies
-- **User Info**: Access controls and authentication
+---
-### 4. Deploy Your First Application
+## 2. Explore the Available Commands
-Let's deploy a simple application to test the workflow:
+OpenFrame CLI is organized into four command groups. Get familiar with each:
```bash
-# Create a test namespace
-kubectl create namespace hello-world
-
-# Deploy a sample application
-kubectl apply -f - <> ~/.bashrc << 'EOF'
-# OpenFrame aliases
-alias of="openframe"
-alias ofcs="openframe cluster status"
-alias ofcl="openframe cluster list"
-alias k="kubectl"
-alias kgp="kubectl get pods"
-alias kgs="kubectl get svc"
-alias kgn="kubectl get nodes"
-EOF
-
-# Reload shell configuration
-source ~/.bashrc
-```
+---
-## Key Workflows to Learn
-
-### Cluster Management Workflow
-
-```mermaid
-flowchart TD
- A[Create Cluster] --> B[Check Status]
- B --> C[Deploy Applications]
- C --> D[Monitor Health]
- D --> E{Issues?}
- E -->|Yes| F[Debug & Fix]
- E -->|No| G[Continue Development]
- F --> D
- G --> H[Scale or Update]
- H --> D
-```
+## 3. Configure Your Local Development Workflow
-#### Common Cluster Commands
-```bash
-# Create a new cluster
-openframe cluster create my-new-cluster
+If you're a developer working on OpenFrame services, set up a service intercept for local development. This routes live Kubernetes traffic from a running service to your local machine.
-# List all clusters
-openframe cluster list
-
-# Get detailed status
-openframe cluster status my-cluster
+### Start an Intercept
-# Delete a cluster
-openframe cluster delete my-cluster
+```bash
+# Interactive mode — select service and port via wizard
+openframe dev intercept
-# Clean up resources
-openframe cluster cleanup
+# Or specify directly
+openframe dev intercept my-api-service --port 8080 --namespace development
```
-### Application Deployment Workflow
-
-```mermaid
-sequenceDiagram
- participant Dev as Developer
- participant CLI as OpenFrame CLI
- participant ArgoCD as ArgoCD
- participant K8s as Kubernetes
-
- Dev->>CLI: openframe chart install
- CLI->>ArgoCD: Create Application
- ArgoCD->>K8s: Deploy Resources
- K8s-->>ArgoCD: Resource Status
- ArgoCD-->>CLI: Sync Status
- CLI-->>Dev: Deployment Complete
-```
+The intercept command will:
-#### Common Chart Commands
-```bash
-# Install a chart from repository
-openframe chart install my-app \
- --repo=https://github.com/my-org/my-app \
- --path=charts/my-app
+1. Validate your kubectl context and cluster connectivity
+2. Connect Telepresence to the cluster
+3. Route traffic from the specified Kubernetes service to your local port
-# List installed applications
-openframe chart list
+### Stop an Intercept
-# Check application sync status
-kubectl get applications -n argocd
+Intercepts are automatically cleaned up when you exit (`Ctrl+C`). The service handles signal cleanup gracefully.
-# Manually sync an application
-kubectl patch application my-app -n argocd \
- --type=json \
- -p='[{"op": "replace", "path": "/spec/syncPolicy", "value": {"automated": {"selfHeal": true}}}]'
-```
+---
-### Development Workflow
+## 4. Run the Skaffold Hot-Reload Workflow
-For local development with live Kubernetes integration:
+For rapid iteration on services, use the Skaffold workflow. This automatically rebuilds and redeploys container images as you change code:
```bash
-# Start a development intercept
-openframe dev intercept my-service \
- --namespace=default \
- --port=3000:8080
-
-# Generate scaffold for new service
-openframe dev scaffold my-new-service \
- --template=microservice \
- --language=go
-```
-
-## Essential Configuration
+# Run Skaffold dev with optional cluster bootstrap
+openframe dev skaffold my-openframe
-### Customize OpenFrame Settings
+# Skip bootstrap if cluster is already running
+openframe dev skaffold my-openframe --skip-bootstrap
-Create a configuration file for personalized settings:
-
-```bash
-mkdir -p ~/.openframe
-cat > ~/.openframe/config.yaml << 'EOF'
-# OpenFrame CLI Configuration
-default:
- cluster_name: "openframe-local"
- namespace: "default"
- log_level: "info"
-
-bootstrap:
- mode: "oss-tenant"
- interactive: true
- timeout: "15m"
-
-cluster:
- provider: "k3d"
- nodes: 1
-
-chart:
- timeout: "10m"
- wait: true
-
-dev:
- intercept_timeout: "5m"
- scaffold_templates_dir: "~/.openframe/templates"
-EOF
+# With a custom helm values file
+openframe dev skaffold my-openframe --helm-values ./values-dev.yaml
```
-### Configure Git Integration
+> The Skaffold workflow handles prerequisite checking, interactive service selection, cluster management, and Helm chart installation automatically.
-For ArgoCD to access your repositories:
-
-```bash
-# Add a Git repository to ArgoCD
-kubectl apply -f - <
- username:
-EOF
-```
+---
-### Set Up Ingress (Optional)
+## 5. Learn the Deployment Modes
-Configure Traefik ingress for external access:
+OpenFrame supports three deployment configurations, selected at bootstrap time via `--deployment-mode`:
```bash
-# Create an ingress for your application
-kubectl apply -f - < -n
+# Create separate clusters for different environments
+openframe cluster create dev-cluster --nodes 2
+openframe cluster create staging-cluster --nodes 4
-# Check logs
-kubectl logs -n
+# Install charts on each independently
+openframe chart install dev-cluster --deployment-mode=oss-tenant
+openframe chart install staging-cluster --deployment-mode=oss-tenant
-# Check resource constraints
-kubectl get resourcequota -n
+# List all clusters
+openframe cluster list
```
-#### Service Not Accessible
-```bash
-# Check service endpoints
-kubectl get endpoints -n
+### Reinstalling Charts
-# Test internal connectivity
-kubectl run test-pod --image=busybox -it --rm -- sh
-# Inside pod:
-wget -q -O- http://..svc.cluster.local
-```
+If you need to reinstall or update charts on an existing cluster without recreating it:
-#### ArgoCD Application Not Syncing
```bash
-# Check application status
-kubectl get application -n argocd -o yaml
-
-# Force refresh
-kubectl patch application -n argocd \
- --type=json \
- -p='[{"op": "replace", "path": "/spec/source/targetRevision", "value": "HEAD"}]'
-
-# Manual sync
-kubectl patch application -n argocd \
- --type=json \
- -p='[{"op": "add", "path": "/metadata/annotations/argocd.argoproj.io~1sync", "value": ""}]'
+openframe chart install my-openframe --deployment-mode=oss-tenant --force
```
-## Best Practices
+### Cleaning Up Resources
-### Development Environment
-1. **Use namespaces**: Organize applications by environment or team
-2. **Resource limits**: Set appropriate CPU/memory limits
-3. **Health checks**: Implement liveness and readiness probes
-4. **Secrets management**: Use Kubernetes secrets, not hardcoded values
+When a cluster is no longer needed:
-### GitOps Workflow
-1. **Infrastructure as Code**: Store all configurations in Git
-2. **Automated sync**: Enable ArgoCD auto-sync for non-production
-3. **Manual approval**: Require manual sync for production deployments
-4. **Rollback strategy**: Use Git reverts for quick rollbacks
+```bash
+# Clean up Docker images and unused resources (keeps cluster)
+openframe cluster cleanup my-openframe
-### Cluster Management
-1. **Regular backups**: Backup cluster state and data
-2. **Monitor resources**: Set up alerts for resource usage
-3. **Update strategy**: Plan regular updates for cluster components
-4. **Security scanning**: Regularly scan images and configurations
+# Fully delete the cluster
+openframe cluster delete my-openframe
+```
-## Next Steps
+---
-Now that you're familiar with OpenFrame basics, explore advanced topics:
+## Verbose Mode
-### Development Workflows
-Learn how to set up a complete development environment:
-- Configure your IDE and editor
-- Set up local development workflows
-- Use service intercepts for debugging
+For troubleshooting or to see detailed logs during any operation, add the `-v` / `--verbose` flag:
-### Architecture Understanding
-Dive deeper into how OpenFrame components work:
-- Study the service architecture
-- Understand data flows and dependencies
-- Learn about security models and best practices
+```bash
+openframe bootstrap my-openframe --verbose
+openframe cluster create my-openframe --verbose
+openframe chart install my-openframe --verbose
+```
-### Advanced Deployment Patterns
-Master sophisticated deployment strategies:
-- Blue/green deployments
-- Canary releases
-- Multi-environment promotion pipelines
+Verbose mode shows:
+- Detailed ArgoCD synchronization progress
+- All Helm operations and outputs
+- Full prerequisite check results
-## Getting Help
+---
-### Community Resources
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) for questions and support
-- **Documentation**: Explore other guides in this repository
-- **Examples**: Check the examples directory for sample configurations
+## Where to Get Help
-### Useful Commands Reference
-```bash
-# Quick status check
-openframe cluster status
+> **Support is handled in the OpenMSP Slack community — not GitHub Issues.**
-# View all resources
-kubectl get all --all-namespaces
+| Resource | Link |
+|---|---|
+| OpenMSP Community | [openmsp.ai](https://www.openmsp.ai/) |
+| Slack Invite | [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) |
+| OpenFrame Platform | [openframe.ai](https://openframe.ai) |
+| Flamingo | [flamingo.run](https://flamingo.run) |
-# Emergency cluster reset
-openframe cluster delete
-openframe bootstrap
+In Slack you can:
+- Ask questions about setup and configuration
+- Report bugs and unexpected behavior
+- Request new features
+- Connect with other MSP operators and developers using OpenFrame
-# Export current configuration
-kubectl get all -o yaml > backup.yaml
+---
-# View OpenFrame CLI logs
-openframe --verbose
-```
+## What's Next
-### Debugging Resources
-- ArgoCD UI: https://localhost:8080 (after port forward)
-- Traefik Dashboard: https://localhost:9000 (after port forward)
-- Kubernetes Dashboard: Install with `kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml`
+After getting comfortable with the basics, explore:
-You're now ready to be productive with OpenFrame CLI! Explore the features, experiment with deployments, and join the community for support and sharing experiences.
\ No newline at end of file
+- The architecture documentation to understand how the CLI components work together
+- The development setup guide for contributing to OpenFrame CLI
+- Security best practices for managing credentials and certificates in your environment
diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md
index 2c2771af..e3c711fb 100644
--- a/docs/getting-started/introduction.md
+++ b/docs/getting-started/introduction.md
@@ -1,142 +1,140 @@
-# Introduction to OpenFrame CLI
+# OpenFrame CLI — Introduction
-OpenFrame CLI is a modern, interactive command-line tool for managing OpenFrame Kubernetes clusters and development workflows. It provides seamless cluster lifecycle management, chart installation with ArgoCD, and developer-friendly tools for service intercepts and scaffolding.
+**OpenFrame CLI** is a modern, interactive command-line tool written in Go that bootstraps and manages OpenFrame Kubernetes environments. It is the primary entry point for spinning up fully functional, production-grade OpenFrame deployments on local or remote Kubernetes clusters — in minutes, not days.
-[](https://www.youtube.com/watch?v=awc-yAnkhIo)
+[](https://www.youtube.com/watch?v=-_56_qYvMWk)
-## What is OpenFrame CLI?
+---
-OpenFrame CLI is part of the broader OpenFrame ecosystem - an AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation. The CLI serves as the entry point for developers and operators to bootstrap, manage, and develop on OpenFrame environments.
+## What Is OpenFrame CLI?
+
+OpenFrame CLI (`openframe`) automates the full lifecycle of an OpenFrame environment:
+
+- **Cluster provisioning** — Creates and manages local K3D Kubernetes clusters
+- **GitOps installation** — Installs ArgoCD and deploys app-of-apps chart patterns
+- **Interactive configuration** — Guides operators through Helm values via a built-in wizard
+- **Developer tooling** — Provides Telepresence service intercepts and Skaffold hot-reload workflows
+
+It is part of the broader [OpenFrame](https://openframe.ai) platform — the unified, AI-driven MSP operations suite built by [Flamingo](https://flamingo.run).
+
+---
## Key Features
-### 🚀 Complete Environment Bootstrapping
-- **One-command setup**: Bootstrap entire OpenFrame environments with `openframe bootstrap`
-- **Multi-mode deployment**: Support for OSS tenant, SaaS tenant, and SaaS shared modes
-- **Automated cluster creation**: Creates K3D clusters with all necessary components
-- **ArgoCD integration**: Automatic chart installation and application management
-
-### 🔧 Cluster Management
-- **Lifecycle operations**: Create, delete, list, and monitor Kubernetes clusters
-- **K3D integration**: Lightweight Kubernetes for development and testing
-- **Status monitoring**: Real-time cluster health and resource monitoring
-- **Easy cleanup**: Remove clusters and associated resources with simple commands
-
-### 📦 Chart & Application Management
-- **Helm chart installation**: Streamlined chart deployment with dependency management
-- **ArgoCD applications**: GitOps-based application lifecycle management
-- **App-of-apps pattern**: Hierarchical application management for complex deployments
-- **Synchronization monitoring**: Track deployment progress with detailed logging
-
-### 🛠 Development Tools
-- **Service intercepts**: Local development with Telepresence integration
-- **Scaffolding**: Generate boilerplate code and configurations
-- **Live debugging**: Debug services running in Kubernetes from your local environment
-- **Hot reload**: Rapid development cycles with instant feedback
+| Feature | Description |
+|---|---|
+| **One-command bootstrap** | `openframe bootstrap` provisions a cluster and installs all charts end-to-end |
+| **Interactive wizard** | Guided Helm values configuration — branch, Docker registry, ingress, deployment mode |
+| **K3D cluster management** | Create, delete, list, status, and cleanup local K3D clusters |
+| **ArgoCD GitOps** | Installs ArgoCD and deploys app-of-apps patterns with health monitoring |
+| **Telepresence intercepts** | Route live Kubernetes traffic to your local machine for rapid iteration |
+| **Skaffold hot-reload** | Rebuild and sync containers on code change within a running cluster |
+| **Non-interactive / CI mode** | All commands support `--non-interactive` flags for CI/CD pipelines |
+| **Cross-platform** | Supports macOS, Linux, and Windows (WSL2) |
+| **Prerequisite auto-installer** | Automatically detects and guides installation of Docker, k3d, kubectl, Helm, and more |
-## Target Audience
+---
-### DevOps Engineers
-- Simplify Kubernetes cluster management
-- Automate deployment pipelines with GitOps
-- Monitor and maintain OpenFrame environments
+## Target Audience
-### Software Developers
-- Develop and test microservices locally
-- Debug applications running in Kubernetes
-- Scaffold new services and components quickly
+OpenFrame CLI is designed for:
-### System Administrators
-- Bootstrap complete OpenFrame environments
-- Manage multiple clusters and deployments
-- Monitor system health and performance
+- **MSP operators** standing up self-hosted OpenFrame environments
+- **Platform engineers** automating GitOps-based Kubernetes deployments
+- **Developers** working on OpenFrame services who need local cluster environments with hot-reload
+- **DevOps / CI/CD pipelines** running non-interactive bootstraps in automated workflows
-### MSP Teams
-- Deploy OpenFrame for multiple tenants
-- Manage client environments efficiently
-- Reduce vendor costs with open-source alternatives
+---
## Architecture Overview
```mermaid
graph TB
- subgraph "CLI Commands"
- Bootstrap[openframe bootstrap]
- Cluster[openframe cluster]
- Chart[openframe chart]
- Dev[openframe dev]
+ subgraph CLI["CLI Layer (cmd/)"]
+ Root["openframe (root)"]
+ BootstrapCmd["bootstrap"]
+ ClusterCmd["cluster"]
+ ChartCmd["chart"]
+ DevCmd["dev"]
end
-
- subgraph "Core Services"
- ClusterSvc[Cluster Management]
- ChartSvc[Chart Installation]
- DevSvc[Development Tools]
+
+ subgraph Services["Internal Services"]
+ BootstrapSvc["Bootstrap Service"]
+ ClusterSvc["Cluster Service"]
+ ChartSvc["Chart Service"]
+ DevSvc["Dev Services"]
end
-
- subgraph "External Tools"
- K3D[K3D Clusters]
- Helm[Helm Charts]
- ArgoCD[ArgoCD Apps]
- Telepresence[Service Intercepts]
+
+ subgraph Providers["External Tool Providers"]
+ K3D["K3D"]
+ Helm["Helm"]
+ ArgoCD["ArgoCD"]
+ Git["Git"]
+ Telepresence["Telepresence"]
+ Skaffold["Skaffold"]
end
-
- subgraph "Target Environment"
- K8s[Kubernetes]
- Apps[Applications]
- Services[Microservices]
+
+ subgraph Target["Deployed Environment"]
+ K8s["Kubernetes Cluster"]
+ Apps["ArgoCD Applications"]
+ Services2["OpenFrame Microservices"]
end
-
- Bootstrap --> ClusterSvc
- Bootstrap --> ChartSvc
- Cluster --> ClusterSvc
- Chart --> ChartSvc
- Dev --> DevSvc
-
+
+ Root --> BootstrapCmd
+ Root --> ClusterCmd
+ Root --> ChartCmd
+ Root --> DevCmd
+
+ BootstrapCmd --> BootstrapSvc
+ ClusterCmd --> ClusterSvc
+ ChartCmd --> ChartSvc
+ DevCmd --> DevSvc
+
+ BootstrapSvc --> ClusterSvc
+ BootstrapSvc --> ChartSvc
+
ClusterSvc --> K3D
ChartSvc --> Helm
ChartSvc --> ArgoCD
+ ChartSvc --> Git
DevSvc --> Telepresence
-
+ DevSvc --> Skaffold
+
K3D --> K8s
Helm --> Apps
ArgoCD --> Apps
- Telepresence --> Services
+ Apps --> Services2
```
-## Key Benefits
+---
-| Benefit | Description |
-|---------|-------------|
-| **Rapid Setup** | Go from zero to running OpenFrame environment in minutes |
-| **Developer Friendly** | Interactive prompts, helpful error messages, and clear documentation |
-| **Production Ready** | Battle-tested components with enterprise-grade reliability |
-| **Open Source** | Complete transparency, community-driven development |
-| **Cost Effective** | Replace expensive proprietary tools with open-source alternatives |
-| **GitOps Native** | Built-in ArgoCD integration for modern deployment practices |
+## Deployment Modes
-## How It Works
+The CLI supports three deployment modes via the `--deployment-mode` flag:
-1. **Bootstrap**: Run `openframe bootstrap` to create a complete environment
-2. **Develop**: Use `openframe dev` commands for local development workflows
-3. **Deploy**: Manage applications with `openframe chart` commands
-4. **Monitor**: Check cluster status with `openframe cluster` commands
+| Mode | Repository | Use Case |
+|---|---|---|
+| `oss-tenant` | `openframe-oss-tenant` | Default self-hosted OpenFrame deployment |
+| `saas-tenant` | `openframe-saas-tenant` | SaaS managed tenant deployment |
+| `saas-shared` | `openframe-saas-shared` | Shared SaaS infrastructure deployment |
-The CLI handles all the complexity of Kubernetes cluster management, chart installations, and development tool configuration, allowing you to focus on building and deploying applications.
+> For most operators getting started, `oss-tenant` is the recommended deployment mode.
-## Next Steps
+---
-Ready to get started? Continue with these guides:
+## Community & Support
-- **[Prerequisites](prerequisites.md)** - Check system requirements and install dependencies
-- **[Quick Start](quick-start.md)** - Get OpenFrame running in 5 minutes
-- **[First Steps](first-steps.md)** - Explore key features and workflows
+OpenFrame issues and discussions are managed in the **OpenMSP Slack community** — not GitHub Issues.
-## Community and Support
+- **Join the community**: [openmsp.ai](https://www.openmsp.ai/)
+- **Slack invite**: [Join OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+- **OpenFrame platform**: [openframe.ai](https://openframe.ai)
+- **Flamingo**: [flamingo.run](https://flamingo.run)
-OpenFrame is built by the community for the community. Get help and connect with other users:
+---
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
-- **Website**: [https://flamingo.run](https://flamingo.run)
-- **OpenFrame Platform**: [https://openframe.ai](https://openframe.ai)
+## Next Steps
-> **Note**: We don't use GitHub Issues or Discussions - all support and community interaction happens in the OpenMSP Slack community.
\ No newline at end of file
+- Review the [Prerequisites Guide](prerequisites.md) to ensure your environment is ready
+- Follow the [Quick Start Guide](quick-start.md) for a 5-minute setup
+- Explore the [First Steps Guide](first-steps.md) after your first successful bootstrap
diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md
index 314e0978..0844af7c 100644
--- a/docs/getting-started/prerequisites.md
+++ b/docs/getting-started/prerequisites.md
@@ -1,315 +1,158 @@
# Prerequisites
-Before installing and using OpenFrame CLI, ensure your system meets the following requirements and has the necessary dependencies installed.
+Before running OpenFrame CLI, ensure your system meets the hardware requirements and has all required software installed. The CLI will also perform its own prerequisite checks and provide guided installation instructions for any missing tools.
-## System Requirements
+---
-### Hardware Requirements
+## Hardware Requirements
-| Resource | Minimum | Recommended |
-|----------|---------|-------------|
-| **RAM** | 24GB | 32GB |
-| **CPU Cores** | 6 cores | 12 cores |
-| **Disk Space** | 50GB free | 100GB free |
-| **Architecture** | x86_64, ARM64 | x86_64, ARM64 |
+| Tier | RAM | CPU Cores | Disk Space |
+|---|---|---|---|
+| **Minimum** | 24 GB | 6 cores | 50 GB |
+| **Recommended** | 32 GB | 12 cores | 100 GB |
-### Operating System Support
+> K3D runs Kubernetes nodes as Docker containers. Insufficient memory is the most common cause of failed bootstraps — ensure Docker has access to at least 16 GB RAM.
-| OS | Version | Status |
-|---|---------|--------|
-| **Linux** | Ubuntu 20.04+, CentOS 8+, RHEL 8+ | ✅ Fully Supported |
-| **macOS** | 11+ (Big Sur and later) | ✅ Fully Supported |
-| **Windows** | Windows 10/11 with WSL2 | ⚠️ Supported via WSL2 |
+---
-> **Windows Users**: OpenFrame CLI requires WSL2 for proper Kubernetes integration. Native Windows support is not currently available.
+## Required Software
-## Required Dependencies
+The OpenFrame CLI depends on the following tools being installed on your system. The CLI will check for these automatically and provide installation guidance if any are missing.
-### Core Dependencies
+### Core Prerequisites (Cluster Operations)
-These tools must be installed before using OpenFrame CLI:
+| Tool | Minimum Version | Purpose | Install Guide |
+|---|---|---|---|
+| **Docker** | 20.10+ | Container runtime for K3D nodes | [docs.docker.com](https://docs.docker.com/get-docker/) |
+| **kubectl** | 1.26+ | Kubernetes CLI for cluster interaction | [kubernetes.io/docs](https://kubernetes.io/docs/tasks/tools/) |
+| **k3d** | 5.6+ | Lightweight Kubernetes via K3D | [k3d.io](https://k3d.io/#installation) |
+| **Helm** | 3.12+ | Kubernetes package manager | [helm.sh](https://helm.sh/docs/intro/install/) |
-| Tool | Version | Purpose | Installation |
-|------|---------|---------|--------------|
-| **Docker** | 20.10+ | Container runtime for K3D clusters | [Docker Install Guide](https://docs.docker.com/get-docker/) |
-| **kubectl** | 1.25+ | Kubernetes command-line tool | [kubectl Install Guide](https://kubernetes.io/docs/tasks/tools/) |
-| **Helm** | 3.10+ | Kubernetes package manager | [Helm Install Guide](https://helm.sh/docs/intro/install/) |
-| **K3D** | 5.0+ | Lightweight Kubernetes clusters | [K3D Install Guide](https://k3d.io/v5.4.6/#installation) |
+### Additional Prerequisites (Chart Installation)
-### Development Dependencies (Optional)
+| Tool | Minimum Version | Purpose | Install Guide |
+|---|---|---|---|
+| **Git** | 2.30+ | Clone app-of-apps chart repositories | [git-scm.com](https://git-scm.com/downloads) |
+| **mkcert** | 1.4+ | Generate local TLS certificates | [github.com/FiloSottile/mkcert](https://github.com/FiloSottile/mkcert) |
-Required only if using development features (`openframe dev` commands):
+### Developer Prerequisites (Dev Workflows Only)
-| Tool | Version | Purpose | Installation |
-|------|---------|---------|--------------|
-| **Telepresence** | 2.10+ | Service intercepts for local development | [Telepresence Install](https://www.telepresence.io/docs/latest/install/) |
-| **jq** | 1.6+ | JSON processing for dev scripts | [jq Install Guide](https://jqlang.github.io/jq/download/) |
+| Tool | Minimum Version | Purpose | Install Guide |
+|---|---|---|---|
+| **Telepresence** | 2.x | Route K8s traffic to local machine | [telepresence.io](https://www.telepresence.io/docs/latest/install/) |
+| **Skaffold** | 2.x | Hot-reload workflow for services | [skaffold.dev](https://skaffold.dev/docs/install/) |
+| **jq** | 1.6+ | JSON processing for dev scripts | [jqlang.github.io](https://jqlang.github.io/jq/download/) |
-## Installation Verification
+---
-### Check Docker
-```bash
-docker --version
-docker ps
-```
-
-Expected output:
-```text
-Docker version 20.10.0 or higher
-CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
-```
-
-### Check kubectl
-```bash
-kubectl version --client
-```
-
-Expected output:
-```text
-Client Version: version.Info{Major:"1", Minor:"25"+...}
-```
-
-### Check Helm
-```bash
-helm version
-```
+## Operating System Support
-Expected output:
-```text
-version.BuildInfo{Version:"v3.10.0"+...}
-```
+| Platform | Status | Notes |
+|---|---|---|
+| **macOS** (Intel / Apple Silicon) | ✅ Fully supported | Docker Desktop or Colima recommended |
+| **Linux** (Ubuntu, Debian, RHEL, Arch) | ✅ Fully supported | Native Docker Engine |
+| **Windows** (WSL2) | ✅ Supported | Requires WSL2 with Docker Desktop or Docker Engine in WSL2 |
-### Check K3D
-```bash
-k3d version
-```
-
-Expected output:
-```text
-k3d version v5.0.0+
-```
+> **Windows users**: The CLI includes special WSL2 integration for Docker, IP detection, and inotify limits. Ensure WSL2 is enabled and Docker is accessible from within your WSL2 distribution.
-### Check Telepresence (Optional)
-```bash
-telepresence version
-```
+---
-Expected output:
-```text
-Client: v2.10.0+
-```
+## OpenFrame CLI Binary
-### Check jq (Optional)
-```bash
-jq --version
-```
+Download the latest `openframe` CLI binary for your platform:
-Expected output:
-```text
-jq-1.6+
-```
+| Platform | Architecture | Download |
+|---|---|---|
+| **macOS** | ARM64 (Apple Silicon) | [openframe-cli_darwin_arm64](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz) |
+| **macOS** | AMD64 (Intel) | [openframe-cli_darwin_amd64](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz) |
+| **Linux** | AMD64 | [openframe-cli_linux_amd64](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz) |
+| **Linux** | ARM64 | [openframe-cli_linux_arm64](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_arm64.tar.gz) |
+| **Windows** | AMD64 | [openframe-cli_windows_amd64.zip](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip) |
-## Network Requirements
-
-### Outbound Connectivity
-OpenFrame CLI requires internet access for:
-- Pulling Docker images
-- Downloading Helm charts
-- Accessing Git repositories
-- Installing prerequisites
-
-### Port Requirements
-| Port Range | Protocol | Purpose |
-|------------|----------|---------|
-| 80, 443 | TCP | HTTPS/HTTP for downloads |
-| 6443 | TCP | Kubernetes API server |
-| 30000-32767 | TCP | Kubernetes NodePort range |
-| 2376, 2377 | TCP | Docker daemon (if remote) |
-
-### Firewall Considerations
-Ensure your firewall allows:
-- Docker daemon communication
-- Kubernetes cluster communication
-- Outbound HTTPS connections
+---
## Environment Variables
-Set these environment variables for optimal experience:
+The following environment variables are recognized by the CLI:
-### Required
-```bash
-# Docker daemon configuration
-export DOCKER_HOST="unix:///var/run/docker.sock"
+| Variable | Purpose | Example |
+|---|---|---|
+| `OPENFRAME_FANCY_LOGO` | Enable/disable fancy terminal logo rendering | `true` / `false` |
+| `NO_COLOR` | Disable all colored terminal output | `1` |
+| `TERM` | Terminal type detection for UI rendering | `xterm-256color` |
+| `KUBECONFIG` | Path to kubeconfig file (standard Kubernetes) | `~/.kube/config` |
-# Kubernetes configuration
-export KUBECONFIG="$HOME/.kube/config"
-```
+---
-### Optional
-```bash
-# OpenFrame CLI configuration
-export OPENFRAME_LOG_LEVEL="info"
-export OPENFRAME_CONFIG_DIR="$HOME/.openframe"
+## Verification Commands
-# Development tools
-export TELEPRESENCE_LOGIN_DOMAIN="auth.datawire.io"
-```
+Run these commands to confirm your environment is ready before running the CLI:
-## Account Requirements
+```bash
+# Verify Docker is running
+docker info
-### Container Registry Access
-- **Public registries**: Docker Hub, GHCR.io (no authentication required)
-- **Private registries**: Configure Docker credentials if using private images
+# Verify kubectl is available
+kubectl version --client
-### Git Repository Access
-- **Public repositories**: No authentication required
-- **Private repositories**: Configure SSH keys or personal access tokens
+# Verify k3d is installed
+k3d version
-## Quick Setup Script
+# Verify Helm is installed
+helm version
-For convenience, here's a script to verify all prerequisites:
+# Verify Git is installed
+git --version
-```bash
-#!/bin/bash
-# prerequisites-check.sh
-
-echo "🔍 Checking OpenFrame CLI prerequisites..."
-
-# Function to check if command exists
-command_exists() {
- command -v "$1" >/dev/null 2>&1
-}
-
-# Function to check version
-check_version() {
- local tool="$1"
- local min_version="$2"
- local current_version="$3"
-
- echo " $tool: $current_version (required: $min_version+)"
-}
-
-errors=0
-
-# Check Docker
-if command_exists docker; then
- docker_version=$(docker --version | cut -d' ' -f3 | cut -d',' -f1)
- check_version "Docker" "20.10.0" "$docker_version"
- if ! docker ps >/dev/null 2>&1; then
- echo " ❌ Docker daemon is not running or accessible"
- ((errors++))
- fi
-else
- echo " ❌ Docker not found"
- ((errors++))
-fi
-
-# Check kubectl
-if command_exists kubectl; then
- kubectl_version=$(kubectl version --client -o json 2>/dev/null | jq -r '.clientVersion.gitVersion' 2>/dev/null || echo "unknown")
- check_version "kubectl" "1.25.0" "$kubectl_version"
-else
- echo " ❌ kubectl not found"
- ((errors++))
-fi
-
-# Check Helm
-if command_exists helm; then
- helm_version=$(helm version --short | cut -d'+' -f1)
- check_version "Helm" "3.10.0" "$helm_version"
-else
- echo " ❌ Helm not found"
- ((errors++))
-fi
-
-# Check K3D
-if command_exists k3d; then
- k3d_version=$(k3d version | grep k3d | cut -d' ' -f2)
- check_version "K3D" "5.0.0" "$k3d_version"
-else
- echo " ❌ K3D not found"
- ((errors++))
-fi
-
-# Check optional tools
-echo ""
-echo "📋 Optional development tools:"
-
-if command_exists telepresence; then
- telepresence_version=$(telepresence version --output=json 2>/dev/null | jq -r '.client.version' 2>/dev/null || "unknown")
- check_version "Telepresence" "2.10.0" "$telepresence_version"
-else
- echo " ⚠️ Telepresence not found (optional for dev workflows)"
-fi
-
-if command_exists jq; then
- jq_version=$(jq --version | cut -d'-' -f2)
- check_version "jq" "1.6" "$jq_version"
-else
- echo " ⚠️ jq not found (optional for dev scripts)"
-fi
-
-echo ""
-if [ $errors -eq 0 ]; then
- echo "✅ All required prerequisites are installed!"
- echo "🚀 You're ready to install OpenFrame CLI"
-else
- echo "❌ $errors required dependencies are missing"
- echo "📖 Please install missing dependencies before proceeding"
- exit 1
-fi
+# Verify mkcert is installed
+mkcert --version
```
-Save this as `prerequisites-check.sh`, make it executable, and run:
+Expected output example for Docker:
-```bash
-chmod +x prerequisites-check.sh
-./prerequisites-check.sh
+```text
+Client:
+ Version: 24.0.5
+ API version: 1.43
+ ...
+Server: Docker Engine - Community
+ Engine:
+ Version: 24.0.5
```
-## Troubleshooting Common Issues
+---
-### Docker Permission Issues
-If you get permission denied errors:
+## Automatic Prerequisite Checking
-```bash
-# Add your user to the docker group
-sudo usermod -aG docker $USER
+The CLI performs automatic prerequisite validation before every operation. If a required tool is missing, it will display:
+
+1. Which tool is missing
+2. Platform-specific installation instructions
+3. An option to attempt automatic installation
-# Log out and back in, or run:
-newgrp docker
+```text
+⚠ Prerequisites check failed:
+ Missing: k3d
+ Install: brew install k3d (macOS)
+ curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash (Linux)
```
-### kubectl Not Finding Config
-```bash
-# Create kubeconfig directory
-mkdir -p ~/.kube
+> You do not need to manually install all tools before first use — the CLI will guide you.
-# Verify KUBECONFIG environment variable
-echo `$KUBECONFIG`
-```
+---
-### K3D Installation Issues on macOS
-```bash
-# If using Homebrew
-brew install k3d
+## Memory Requirements for K3D
-# If using curl
-curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
-```
+The CLI checks available system memory before cluster creation. A typical OpenFrame deployment requires:
-### WSL2 Setup on Windows
-1. Enable WSL2: `wsl --install`
-2. Install Ubuntu from Microsoft Store
-3. Install Docker Desktop with WSL2 backend
-4. Install all prerequisites inside WSL2 environment
+- **Minimum**: 8 GB available to Docker
+- **Recommended**: 16 GB+ available to Docker
-## Next Steps
+On macOS with Docker Desktop, ensure the memory limit in Docker Desktop preferences is set to at least 16 GB.
-Once all prerequisites are installed and verified:
+---
-1. **[Quick Start Guide](quick-start.md)** - Install OpenFrame CLI and bootstrap your first environment
-2. **[First Steps Guide](first-steps.md)** - Explore key features and workflows
+## Next Steps
-Need help? Join our community:
-- **OpenMSP Slack**: [Join here](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
\ No newline at end of file
+- Follow the [Quick Start Guide](quick-start.md) to bootstrap your first environment
+- Read the [First Steps Guide](first-steps.md) once your environment is running
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index 72253b3f..c9242081 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -1,355 +1,208 @@
-# Quick Start Guide
+# Quick Start
-Get OpenFrame CLI up and running in 5 minutes! This guide will walk you through installing OpenFrame CLI and bootstrapping your first environment.
+Get a fully operational OpenFrame environment running in under 5 minutes using the `openframe bootstrap` command.
-[](https://www.youtube.com/watch?v=er-z6IUnAps)
+[](https://www.youtube.com/watch?v=awc-yAnkhIo)
-## TL;DR - 5-Minute Setup
+---
-If you have all prerequisites installed, here's the fastest path:
+## TL;DR
```bash
-# 1. Download and install OpenFrame CLI (choose your platform)
-# Linux/macOS
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz
+# 1. Download the CLI for your platform (example: macOS Apple Silicon)
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar xz
+chmod +x openframe
sudo mv openframe /usr/local/bin/
-# Windows (download manually)
-# Download: https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip
-
-# 2. Verify installation
-openframe --version
-
-# 3. Bootstrap complete environment
+# 2. Bootstrap a complete environment interactively
openframe bootstrap
-
-# 4. Check cluster status
-openframe cluster status
```
-That's it! Continue reading for detailed steps and explanations.
+That's it. The `bootstrap` command will:
-## Step 1: Install OpenFrame CLI
+1. Check and guide installation of any missing prerequisites (Docker, k3d, kubectl, Helm, Git, mkcert)
+2. Create a local K3D Kubernetes cluster
+3. Install ArgoCD via Helm
+4. Clone and deploy the app-of-apps GitOps chart
+5. Wait for all ArgoCD applications to become Healthy and Synced
-### Option A: Download Pre-built Binary (Recommended)
+---
-Choose your platform and download the latest release:
+## Step 1 — Install the CLI
-#### Linux (AMD64)
-```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar -xz
-sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
-```
+### macOS (Apple Silicon)
-#### Linux (ARM64)
```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_arm64.tar.gz | tar -xz
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar xz
+chmod +x openframe
sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
```
-#### macOS (AMD64)
-```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz | tar -xz
-sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
-```
+### macOS (Intel)
-#### macOS (Apple Silicon)
```bash
-curl -fsSL https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_arm64.tar.gz | tar -xz
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_darwin_amd64.tar.gz | tar xz
+chmod +x openframe
sudo mv openframe /usr/local/bin/
-chmod +x /usr/local/bin/openframe
```
-#### Windows (AMD64)
-1. Download: https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip
-2. Extract the ZIP file
-3. Move `openframe.exe` to a directory in your `PATH`
-4. Open WSL2 terminal and verify access
-
-### Option B: Build from Source
-
-If you have Go 1.24.6+ installed:
+### Linux (AMD64)
```bash
-# Clone the repository
-git clone https://github.com/flamingo-stack/openframe-cli.git
-cd openframe-cli
-
-# Build the binary
-go build -o openframe main.go
-
-# Move to PATH
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_amd64.tar.gz | tar xz
+chmod +x openframe
sudo mv openframe /usr/local/bin/
```
-## Step 2: Verify Installation
-
-Confirm OpenFrame CLI is installed correctly:
+### Linux (ARM64)
```bash
-openframe --version
+curl -L https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_linux_arm64.tar.gz | tar xz
+chmod +x openframe
+sudo mv openframe /usr/local/bin/
```
-Expected output:
-```text
-openframe version v1.x.x (commit: abc123, built: 2024-01-01)
-```
+### Windows (AMD64)
-Check available commands:
-```bash
-openframe --help
-```
+1. Download: [openframe-cli_windows_amd64.zip](https://github.com/flamingo-stack/openframe-cli/releases/latest/download/openframe-cli_windows_amd64.zip)
+2. Extract the zip archive
+3. Move `openframe.exe` to a directory in your `PATH` (e.g., `C:\Windows\System32\` or a custom tools folder)
-You should see the main command groups:
-- `bootstrap` - Complete environment setup
-- `cluster` - Kubernetes cluster management
-- `chart` - Helm chart and ArgoCD management
-- `dev` - Development tools and workflows
+> **Windows users**: Run all commands from a WSL2 terminal for the best experience.
-## Step 3: Bootstrap Your First Environment
+---
-The bootstrap command creates a complete OpenFrame environment with a single command:
+## Step 2 — Verify Installation
```bash
-openframe bootstrap
+openframe --help
```
-### Interactive Bootstrap
-
-The command will guide you through setup with prompts:
+Expected output:
```text
-🚀 OpenFrame Bootstrap Wizard
-
-? Select deployment mode:
- > oss-tenant (Single tenant, open source)
- saas-tenant (Multi-tenant SaaS mode)
- saas-shared (Shared SaaS infrastructure)
-
-? Enable verbose logging? (y/N): y
+ ___ ___
+ / _ \ _ __ ___ _ __ | _|_ __ __ _ _ __ ___ ___
+ | | | | '_ \ / _ \ '_ \ | |_| '__/ _` | '_ ` _ \ / _ \
+ | |_| | |_) | __/ | | || _| | | (_| | | | | | | __/
+ \___/| .__/ \___|_| |_||_| |_| \__,_|_| |_| |_|\___|
+ |_|
-🔍 Checking prerequisites...
-✅ Docker is running
-✅ kubectl is available
-✅ Helm is available
-✅ K3D is available
+Usage:
+ openframe [command]
-🎯 Creating K3D cluster...
-✅ Cluster 'openframe-local' created
+Available Commands:
+ bootstrap Bootstrap a complete OpenFrame environment
+ chart Manage OpenFrame Helm charts
+ cluster Manage Kubernetes clusters
+ dev Development workflow tools
+ help Help about any command
-🎭 Installing ArgoCD...
-✅ ArgoCD installed and ready
+Flags:
+ -h, --help help for openframe
+ -v, --verbose Enable verbose output
-📦 Installing application charts...
-✅ App-of-apps synchronized
-✅ All applications healthy
-
-🎉 OpenFrame environment is ready!
+Use "openframe [command] --help" for more information about a command.
```
-### Non-Interactive Bootstrap
+---
-For scripts and CI/CD, use flags to skip prompts:
+## Step 3 — Bootstrap Your First Environment
-```bash
-openframe bootstrap \
- --mode=oss-tenant \
- --non-interactive \
- --verbose
-```
+### Interactive Mode (Recommended for First-Time Users)
-## Step 4: Verify Your Environment
-
-### Check Cluster Status
```bash
-openframe cluster status
-```
-
-Expected output:
-```text
-📊 Cluster Status: openframe-local
-
-Cluster Info:
- Name: openframe-local
- Status: Running ✅
- Nodes: 1 (1 ready)
- Kubernetes Version: v1.28.6+k3s1
-
-Resource Usage:
- CPU: 2 cores (25% used)
- Memory: 8Gi (45% used)
- Storage: 50Gi (12% used)
-
-Key Services:
- ArgoCD: Healthy ✅
- Traefik: Healthy ✅
- CoreDNS: Healthy ✅
-```
-
-### Access ArgoCD UI
-The bootstrap process installs ArgoCD. Access the web interface:
-
-```bash
-# Get ArgoCD URL and credentials
-kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
-kubectl port-forward svc/argocd-server -n argocd 8080:443
+openframe bootstrap
```
-Then open: http://localhost:8080
-- Username: `admin`
-- Password: (from the command above)
+The interactive wizard will guide you through:
-### View Running Applications
-```bash
-# List all pods across namespaces
-kubectl get pods --all-namespaces
+1. **Cluster name** — Enter a name for your K3D cluster (e.g., `my-openframe`)
+2. **Deployment mode** — Select `oss-tenant` for a standard self-hosted deployment
+3. **Configuration mode** — Choose `default` for sensible defaults, or `interactive` for full customization
+4. **Branch / Docker / Ingress** — Customize if using interactive configuration mode
-# Check ArgoCD applications
-kubectl get applications -n argocd
-```
-
-## Step 5: Test Basic Functionality
+### Non-Interactive Mode (CI/CD)
-### Create a Test Namespace
```bash
-kubectl create namespace test-app
-kubectl get namespaces
+openframe bootstrap my-cluster --deployment-mode=oss-tenant --non-interactive
```
-### Deploy a Simple Application
-```bash
-# Create a test deployment
-kubectl create deployment nginx --image=nginx:latest -n test-app
-kubectl expose deployment nginx --port=80 --target-port=80 -n test-app
-
-# Check deployment
-kubectl get pods -n test-app
-kubectl get svc -n test-app
-```
+---
-### Test Service Access
-```bash
-# Port forward to test connectivity
-kubectl port-forward svc/nginx -n test-app 8081:80 &
+## Step 4 — Watch the Bootstrap Progress
-# Test the service
-curl http://localhost:8081
+The bootstrap command will display real-time progress:
-# Clean up
-kill %1 # Stop port-forward
-kubectl delete namespace test-app
+```text
+✓ Checking prerequisites...
+✓ Creating K3D cluster: my-openframe
+✓ Configuring kubeconfig
+✓ Installing ArgoCD via Helm
+✓ Cloning app-of-apps chart repository
+✓ Installing app-of-apps chart
+⏳ Waiting for ArgoCD applications to sync...
+ ● openframe-core Healthy ✓
+ ● openframe-frontend Progressing...
+ ● openframe-db Healthy ✓
+✓ All applications Healthy and Synced
+✓ Bootstrap complete!
```
-## What Just Happened?
-
-The bootstrap process created:
-
-1. **K3D Cluster**: A lightweight Kubernetes cluster running in Docker
-2. **ArgoCD**: GitOps deployment tool for application management
-3. **Traefik**: Ingress controller for routing traffic
-4. **Core Services**: DNS, metrics, and monitoring components
-5. **Application Templates**: Ready-to-use deployment patterns
+> Typical bootstrap time: **5–15 minutes** depending on network speed and hardware.
-## Expected Results
+---
-After successful bootstrap:
+## Step 5 — Verify Your Environment
-| Component | Status | Access Method |
-|-----------|--------|---------------|
-| **Kubernetes API** | ✅ Running | `kubectl` commands |
-| **ArgoCD UI** | ✅ Running | Port forward to 8080 |
-| **Traefik Dashboard** | ✅ Running | Port forward to 9000 |
-| **Container Registry** | ✅ Running | Docker daemon |
-
-## Troubleshooting
-
-### Bootstrap Fails with Docker Error
```bash
-# Check Docker status
-docker ps
-docker info
+# Check cluster status
+openframe cluster status my-openframe
-# Restart Docker if needed
-sudo systemctl restart docker # Linux
-# or restart Docker Desktop on macOS/Windows
+# List all clusters
+openframe cluster list
```
-### Kubectl Cannot Connect
-```bash
-# Check kubeconfig
-kubectl config current-context
-kubectl config get-contexts
+---
-# Switch to openframe context if needed
-kubectl config use-context k3d-openframe-local
-```
+## Alternative: Step-by-Step Approach
-### ArgoCD Not Accessible
-```bash
-# Check ArgoCD pods
-kubectl get pods -n argocd
+If you prefer more control, run cluster creation and chart installation separately:
-# Restart ArgoCD if needed
-kubectl rollout restart deployment argocd-server -n argocd
-```
-
-### Port Already in Use
```bash
-# Find and kill processes using required ports
-lsof -ti:6443,8080,9000 | xargs kill -9
+# Step 1: Create cluster only
+openframe cluster create my-openframe --nodes 4 --skip-wizard
-# Or use different ports
-kubectl port-forward svc/argocd-server -n argocd 8081:443
+# Step 2: Install charts on the cluster
+openframe chart install my-openframe --deployment-mode=oss-tenant
```
-## Next Steps
+---
-🎉 **Congratulations!** You now have a running OpenFrame environment. Here's what to explore next:
+## Expected Result
-- **[First Steps Guide](first-steps.md)** - Learn key workflows and features
-- **[Architecture Overview](../development/architecture/README.md)** - Understand how components work together
-- **[Development Setup](../development/setup/local-development.md)** - Configure your development environment
+After a successful bootstrap you will have:
-## Common Next Actions
+- A running K3D Kubernetes cluster
+- ArgoCD installed and accessible
+- All OpenFrame applications deployed and synced via GitOps
+- A local kubeconfig configured to access the cluster
-### Deploy Your First Application
-```bash
-# Use ArgoCD to deploy from Git
-openframe chart install my-app \
- --repo=https://github.com/your-org/your-app \
- --path=helm-chart
-```
+---
-### Start Local Development
-```bash
-# Intercept a service for local development
-openframe dev intercept my-service \
- --namespace=default \
- --port=8080:3000
-```
+## Troubleshooting Quick Reference
-### Explore the Environment
-```bash
-# List available commands
-openframe --help
-
-# Get cluster information
-openframe cluster list
-openframe cluster status
+| Issue | Likely Cause | Fix |
+|---|---|---|
+| Docker not found | Docker not installed or not running | Start Docker Desktop / Docker daemon |
+| Memory errors | Insufficient RAM allocated to Docker | Increase Docker memory limit to 16 GB+ |
+| Bootstrap hangs on ArgoCD sync | Slow image pulls on first run | Wait — large images take time on first bootstrap |
+| `k3d: command not found` | k3d not installed | CLI will offer to install it; or run `brew install k3d` |
+| Port conflicts | Another service using required ports | Stop conflicting services before bootstrap |
-# Check chart installations
-openframe chart list
-```
-
-## Getting Help
+---
-Need assistance? The OpenFrame community is here to help:
-
-- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
-- **Documentation**: Browse other guides in this repository
-- **GitHub Issues**: Report bugs or request features (but use Slack for general support)
+## Next Steps
-> **Note**: All community support happens in Slack - we don't monitor GitHub Issues for support requests.
\ No newline at end of file
+- Read the [First Steps Guide](first-steps.md) to explore your newly bootstrapped environment
+- Check the [Prerequisites Guide](prerequisites.md) if you encounter tool-related errors
diff --git a/docs/architecture/.gitignore b/docs/reference/architecture/.gitignore
similarity index 100%
rename from docs/architecture/.gitignore
rename to docs/reference/architecture/.gitignore
diff --git a/docs/reference/architecture/overview.md b/docs/reference/architecture/overview.md
new file mode 100644
index 00000000..79dd1c7f
--- /dev/null
+++ b/docs/reference/architecture/overview.md
@@ -0,0 +1,463 @@
+# openframe-cli Module Documentation
+
+# OpenFrame CLI — Architecture Documentation
+
+[](https://www.youtube.com/watch?v=bINdW0CQbvY)
+
+---
+
+## Overview
+
+OpenFrame CLI is a modern, interactive command-line tool written in Go that bootstraps and manages OpenFrame Kubernetes environments. It orchestrates the full lifecycle of local K3D clusters, installs ArgoCD with app-of-apps GitOps patterns, and provides developer-focused tools for service intercepts (via Telepresence) and Skaffold-based hot-reload workflows. The CLI is the primary entry point for both interactive human operators and fully automated CI/CD pipelines.
+
+---
+
+## Architecture
+
+### High-Level Architecture Diagram
+
+```mermaid
+graph TB
+ subgraph CLI["CLI Layer (cmd/)"]
+ Root["root.go"]
+ BootstrapCmd["bootstrap"]
+ ClusterCmd["cluster"]
+ ChartCmd["chart"]
+ DevCmd["dev"]
+ end
+
+ subgraph Internal["Internal Services (internal/)"]
+ BootstrapSvc["bootstrap/service.go"]
+ ClusterSvc["cluster/service.go"]
+ ChartSvc["chart/services/"]
+ DevSvc["dev/services/"]
+ end
+
+ subgraph Providers["Providers"]
+ K3dProvider["cluster/providers/k3d"]
+ HelmProvider["chart/providers/helm"]
+ ArgoCDProvider["chart/providers/argocd"]
+ GitProvider["chart/providers/git"]
+ KubectlProvider["dev/providers/kubectl"]
+ TelepresenceProvider["dev/providers/telepresence"]
+ end
+
+ subgraph External["External Tools"]
+ K3D["K3D"]
+ Helm["Helm"]
+ ArgoCD["ArgoCD"]
+ Git["Git"]
+ Telepresence["Telepresence"]
+ Skaffold["Skaffold"]
+ Docker["Docker"]
+ Kubectl["kubectl"]
+ end
+
+ subgraph Shared["Shared Infrastructure (internal/shared/)"]
+ Executor["executor"]
+ Errors["errors"]
+ UI["ui"]
+ Config["config"]
+ Files["files"]
+ Flags["flags"]
+ end
+
+ subgraph Target["Target Environment"]
+ K8s["Kubernetes Cluster"]
+ Apps["ArgoCD Applications"]
+ Services["Microservices"]
+ end
+
+ Root --> BootstrapCmd
+ Root --> ClusterCmd
+ Root --> ChartCmd
+ Root --> DevCmd
+
+ BootstrapCmd --> BootstrapSvc
+ ClusterCmd --> ClusterSvc
+ ChartCmd --> ChartSvc
+ DevCmd --> DevSvc
+
+ BootstrapSvc --> ClusterSvc
+ BootstrapSvc --> ChartSvc
+
+ ClusterSvc --> K3dProvider
+ ChartSvc --> HelmProvider
+ ChartSvc --> ArgoCDProvider
+ ChartSvc --> GitProvider
+ DevSvc --> KubectlProvider
+ DevSvc --> TelepresenceProvider
+
+ K3dProvider --> K3D
+ HelmProvider --> Helm
+ ArgoCDProvider --> ArgoCD
+ GitProvider --> Git
+ TelepresenceProvider --> Telepresence
+ DevSvc --> Skaffold
+ K3dProvider --> Docker
+ KubectlProvider --> Kubectl
+
+ K3D --> K8s
+ Helm --> Apps
+ ArgoCD --> Apps
+ Telepresence --> Services
+
+ ClusterSvc --> Shared
+ ChartSvc --> Shared
+ DevSvc --> Shared
+```
+
+---
+
+## Core Components
+
+| Package | Path | Responsibility |
+|---|---|---|
+| **Root Command** | `cmd/root.go` | Entry point; wires all subcommands, version info, global flags |
+| **Bootstrap Command** | `cmd/bootstrap/` | Orchestrates cluster creation + chart installation in one command |
+| **Cluster Command** | `cmd/cluster/` | Subcommands: create, delete, list, status, cleanup |
+| **Chart Command** | `cmd/chart/` | Subcommands: install (ArgoCD + app-of-apps) |
+| **Dev Command** | `cmd/dev/` | Subcommands: intercept, skaffold |
+| **Bootstrap Service** | `internal/bootstrap/service.go` | Sequentially calls cluster create then chart install; handles Windows WSL init |
+| **Cluster Service** | `internal/cluster/service.go` | Business logic for cluster lifecycle; wraps K3D manager |
+| **K3D Manager** | `internal/cluster/providers/k3d/manager.go` | Low-level K3D operations via CLI; produces `rest.Config` |
+| **Chart Service** | `internal/chart/services/chart_service.go` | Orchestrates ArgoCD + app-of-apps installation workflow |
+| **Helm Manager** | `internal/chart/providers/helm/manager.go` | Helm operations using native Go clients + kubectl fallback |
+| **ArgoCD Manager** | `internal/chart/providers/argocd/applications.go` | Watches ArgoCD application health/sync via native K8s clients |
+| **Git Repository** | `internal/chart/providers/git/repository.go` | Shallow-clones app-of-apps chart repo to temp dir |
+| **Intercept Service** | `internal/dev/services/intercept/service.go` | Manages Telepresence intercept lifecycle |
+| **Scaffold Service** | `internal/dev/services/scaffold/service.go` | Runs Skaffold dev workflow with cluster bootstrap |
+| **Configuration Wizard** | `internal/chart/ui/configuration/wizard.go` | Interactive Helm values configuration (deployment mode, ingress, Docker, SaaS) |
+| **Shared Executor** | `internal/shared/executor/executor.go` | Command execution abstraction (real + mock); handles WSL on Windows |
+| **Shared Errors** | `internal/shared/errors/errors.go` | Structured error types, retry policies, user-friendly error display |
+| **Shared UI** | `internal/shared/ui/` | Prompts, tables, logo, progress tracking via pterm/promptui |
+| **Shared Config** | `internal/shared/config/` | TLS config helpers, credentials prompter, system initialization |
+| **Prerequisites (cluster)** | `internal/cluster/prerequisites/` | Checks/installs Docker, kubectl, k3d, helm |
+| **Prerequisites (chart)** | `internal/chart/prerequisites/` | Checks/installs git, helm, mkcert, memory |
+| **Prerequisites (dev)** | `internal/dev/prerequisites/` | Checks/installs Telepresence, jq, Skaffold |
+| **Cluster Models** | `internal/cluster/models/` | `ClusterConfig`, `ClusterInfo`, flag types, domain errors |
+| **Chart Models** | `internal/chart/models/` | `AppOfAppsConfig`, `ChartInfo`, chart types |
+| **Flag Container** | `internal/cluster/types.go` | Holds all flag structs; dependency injection point for testing |
+| **Test Utilities** | `tests/testutil/` | Mock executors, flag factories, assertion helpers |
+
+---
+
+## Component Relationships
+
+### Dependency Graph
+
+```mermaid
+graph LR
+ subgraph Commands["cmd/"]
+ RC["root.go"]
+ BC["bootstrap"]
+ CC["cluster/*"]
+ CHC["chart/*"]
+ DC["dev/*"]
+ end
+
+ subgraph Services["internal/*/services"]
+ BS["bootstrap.Service"]
+ CS["cluster.ClusterService"]
+ CHS["chart.ChartService"]
+ IS["intercept.Service"]
+ SS["scaffold.Service"]
+ end
+
+ subgraph Providers["internal/*/providers"]
+ K3DP["k3d.Manager"]
+ HP["helm.HelmManager"]
+ AP["argocd.Manager"]
+ GP["git.Repository"]
+ KP["kubectl.Provider"]
+ TP["telepresence.Provider"]
+ end
+
+ subgraph SharedInfra["internal/shared/"]
+ EX["executor"]
+ ERR["errors"]
+ UIL["ui"]
+ CFG["config"]
+ end
+
+ RC --> BC
+ RC --> CC
+ RC --> CHC
+ RC --> DC
+
+ BC --> BS
+ CC --> CS
+ CHC --> CHS
+ DC --> IS
+ DC --> SS
+
+ BS --> CS
+ BS --> CHS
+
+ CS --> K3DP
+ CHS --> HP
+ CHS --> AP
+ CHS --> GP
+ IS --> KP
+ IS --> TP
+ SS --> KP
+ SS --> CHS
+
+ K3DP --> EX
+ HP --> EX
+ AP --> EX
+ GP --> EX
+ KP --> EX
+ TP --> EX
+
+ CS --> ERR
+ CHS --> ERR
+ IS --> ERR
+
+ CS --> UIL
+ CHS --> UIL
+ IS --> UIL
+ SS --> UIL
+
+ HP --> CFG
+ AP --> CFG
+ K3DP --> CFG
+```
+
+---
+
+## Data Flow
+
+### Bootstrap Command Sequence
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant CLI as "openframe bootstrap"
+ participant Bootstrap as "bootstrap.Service"
+ participant ClusterSvc as "cluster.ClusterService"
+ participant K3dMgr as "k3d.Manager"
+ participant ChartSvc as "chart.ChartService"
+ participant HelmMgr as "helm.HelmManager"
+ participant ArgoCDMgr as "argocd.Manager"
+ participant GitRepo as "git.Repository"
+
+ User->>CLI: openframe bootstrap [cluster-name]
+ CLI->>Bootstrap: Execute(cmd, args)
+ Bootstrap->>Bootstrap: Validate flags (mode, non-interactive)
+
+ Bootstrap->>ClusterSvc: CreateClusterWithPrerequisitesNonInteractive()
+ ClusterSvc->>ClusterSvc: CheckPrerequisites (Docker, k3d, kubectl, helm)
+ ClusterSvc->>K3dMgr: CreateCluster(config)
+ K3dMgr->>K3dMgr: createK3dConfigFile()
+ K3dMgr-->>ClusterSvc: *rest.Config
+ ClusterSvc-->>Bootstrap: *rest.Config
+
+ Bootstrap->>ChartSvc: InstallChartsWithConfig(request)
+ ChartSvc->>ChartSvc: CheckPrerequisites (git, helm, mkcert)
+ ChartSvc->>ChartSvc: ConfigureHelmValues (wizard or non-interactive)
+
+ ChartSvc->>HelmMgr: InstallArgoCDWithProgress(ctx, config)
+ HelmMgr-->>ChartSvc: ArgoCD installed
+
+ ChartSvc->>GitRepo: CloneChartRepository(appOfAppsConfig)
+ GitRepo-->>ChartSvc: CloneResult (tempDir, chartPath)
+
+ ChartSvc->>HelmMgr: InstallAppOfAppsFromLocal(ctx, config, certFile, keyFile)
+ HelmMgr-->>ChartSvc: app-of-apps installed
+
+ ChartSvc->>ArgoCDMgr: WaitForApplications(ctx, config)
+ ArgoCDMgr->>ArgoCDMgr: Poll ArgoCD Application CRDs
+ ArgoCDMgr-->>ChartSvc: All apps Healthy + Synced
+
+ ChartSvc-->>Bootstrap: nil (success)
+ Bootstrap-->>CLI: nil
+ CLI-->>User: Bootstrap complete
+```
+
+### Chart Install Interactive Configuration Flow
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Workflow as "InstallationWorkflow"
+ participant Wizard as "ConfigurationWizard"
+ participant Modifier as "HelmValuesModifier"
+ participant Builder as "config.Builder"
+ participant Installer as "chart.Installer"
+
+ User->>Workflow: ExecuteWithContext(ctx, req)
+ Workflow->>Workflow: SelectCluster (interactive or arg)
+ Workflow->>Wizard: ConfigureHelmValues()
+ Wizard->>User: Select deployment mode (OSS/SaaS/SaaS-Shared)
+ User-->>Wizard: oss-tenant
+ Wizard->>User: Select config mode (default/interactive)
+ User-->>Wizard: interactive
+ Wizard->>Modifier: LoadOrCreateBaseValues()
+ Modifier-->>Wizard: map[string]interface{}
+ Wizard->>User: Configure branch / Docker / Ingress
+ User-->>Wizard: selections
+ Wizard->>Modifier: ApplyConfiguration(values, config)
+ Wizard->>Modifier: CreateTemporaryValuesFile(values)
+ Modifier-->>Wizard: helm-values-tmp.yaml
+ Wizard-->>Workflow: ChartConfiguration
+
+ Workflow->>Builder: BuildInstallConfig(...)
+ Builder->>Builder: getBranchFromHelmValues()
+ Builder-->>Workflow: ChartInstallConfig
+
+ Workflow->>Installer: InstallChartsWithContext(ctx, config)
+ Installer->>Installer: ArgoCD install
+ Installer->>Installer: app-of-apps install
+ Installer->>Installer: WaitForApplications
+ Installer-->>Workflow: success
+```
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `main.go` | Binary entry point; delegates to `cmd.Execute()` |
+| `cmd/root.go` | Builds root Cobra command; registers all subcommands and global flags |
+| `cmd/bootstrap/bootstrap.go` | `openframe bootstrap` — flags, args, delegates to service |
+| `cmd/cluster/create.go` | `openframe cluster create` — wizard or skip-wizard mode |
+| `cmd/chart/install.go` | `openframe chart install` — flag extraction, delegates to `InstallChartsWithConfig` |
+| `cmd/dev/intercept.go` | `openframe dev intercept` — interactive cluster/service selection then Telepresence |
+| `cmd/dev/scaffold.go` | `openframe dev skaffold` — Skaffold dev workflow with optional bootstrap |
+| `internal/bootstrap/service.go` | Core bootstrap orchestration (cluster → charts); Windows WSL handling |
+| `internal/cluster/service.go` | `ClusterService`: create, delete, list, status, cleanup business logic |
+| `internal/cluster/providers/k3d/manager.go` | K3D cluster operations; returns `*rest.Config`; platform-specific paths |
+| `internal/cluster/models/cluster.go` | `ClusterConfig`, `ClusterInfo`, `ClusterType` domain types |
+| `internal/cluster/models/flags.go` | All flag structs; `ValidateClusterName`; flag registration helpers |
+| `internal/cluster/utils/cmd_helpers.go` | Global flag container, service factory, command wrapper, test injection |
+| `internal/chart/services/chart_service.go` | `ChartService`: workflow orchestration, cluster selection, deferred Helm init |
+| `internal/chart/services/installer.go` | `Installer`: ArgoCD then app-of-apps then wait for sync |
+| `internal/chart/services/appofapps.go` | `AppOfApps`: git clone → local Helm install |
+| `internal/chart/services/argocd.go` | `ArgoCD`: Helm install + `WaitForApplications` delegation |
+| `internal/chart/providers/argocd/applications.go` | Native K8s client-based ArgoCD app health monitoring |
+| `internal/chart/providers/argocd/wait.go` | Application readiness polling with spinner, signal handling, repo-server recovery |
+| `internal/chart/providers/helm/manager.go` | Helm CLI execution with native Go K8s clients for verification |
+| `internal/chart/providers/git/repository.go` | Shallow git clone to temp dir with cleanup |
+| `internal/chart/ui/configuration/wizard.go` | Helm values configuration wizard (deployment mode → sections) |
+| `internal/chart/ui/configuration/modes.go` | Interactive deployment mode and configuration mode selection |
+| `internal/chart/utils/config/builder.go` | `ChartInstallConfig` construction; reads branch from helm-values.yaml |
+| `internal/chart/utils/config/paths.go` | Path resolution for certs, manifests, helm values |
+| `internal/chart/utils/types/interfaces.go` | All service interfaces + `InstallationRequest` type |
+| `internal/dev/services/intercept/service.go` | Telepresence intercept lifecycle management |
+| `internal/dev/services/scaffold/service.go` | Skaffold dev workflow: discover config → bootstrap → run skaffold dev |
+| `internal/dev/providers/kubectl/provider.go` | kubectl-based namespace/service discovery |
+| `internal/dev/ui/intercept.go` | Interactive service/port/namespace selection for intercepts |
+| `internal/shared/executor/executor.go` | `CommandExecutor` interface, real implementation, WSL helpers |
+| `internal/shared/executor/mock.go` | `MockCommandExecutor` for unit tests |
+| `internal/shared/errors/errors.go` | Structured error types; `ErrorHandler` with user-friendly display |
+| `internal/shared/errors/retry_policy.go` | Exponential/linear backoff retry policies |
+| `internal/shared/config/transport.go` | `ApplyInsecureTLSConfig` for k3d local cluster TLS bypass |
+| `internal/shared/ui/logo.go` | OpenFrame ASCII logo rendering; terminal detection |
+| `internal/shared/ui/prompts.go` | `SelectFromList`, `ConfirmAction`, `GetInput` interactive prompts |
+| `internal/shared/ui/messages/templates.go` | Standardized message templates with pterm |
+| `tests/testutil/setup.go` | `CreateStandardTestFlags` with mock executor; `CreateIntegrationTestFlags` |
+| `tests/integration/common/cli_runner.go` | Builds CLI binary and executes it for integration testing |
+
+---
+
+## Dependencies
+
+The project uses the following key library dependencies and how they are consumed:
+
+| Library | Usage in OpenFrame CLI |
+|---|---|
+| **[spf13/cobra](https://github.com/spf13/cobra)** | All CLI command structure, flag parsing, subcommand routing, `SilenceErrors`/`SilenceUsage` |
+| **[pterm/pterm](https://github.com/pterm/pterm)** | Spinners, progress bars, tables, boxes, colored output, interactive confirms throughout all UI layers |
+| **[manifoldco/promptui](https://github.com/manifoldco/promptui)** | `Select` menus and `Prompt` text inputs in wizards and cluster UI |
+| **[k8s.io/client-go](https://pkg.go.dev/k8s.io/client-go)** | Native Kubernetes API access: `rest.Config`, `kubernetes.Interface`, kubeconfig loading via `clientcmd` |
+| **[k8s.io/apiextensions-apiserver](https://pkg.go.dev/k8s.io/apiextensions-apiserver)** | CRD existence checks (waits for ArgoCD CRDs before polling applications) |
+| **[argoproj/argo-cd/v2](https://pkg.go.dev/github.com/argoproj/argo-cd/v2)** | Native ArgoCD client (`argocdclientset`) for application health/sync monitoring |
+| **[k8s.io/apimachinery](https://pkg.go.dev/k8s.io/apimachinery)** | Unstructured resources, `schema.GroupVersionResource`, `metav1` types |
+| **[k8s.io/client-go/dynamic](https://pkg.go.dev/k8s.io/client-go/dynamic)** | Dynamic Kubernetes resource operations for Helm release verification |
+| **[sigs.k8s.io/yaml](https://pkg.go.dev/sigs.k8s.io/yaml)** | YAML marshaling/unmarshaling for Helm values files and K8s resources |
+| **[gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3)** | YAML parsing for `helm-values.yaml` reading and writing |
+| **[golang.org/x/term](https://pkg.go.dev/golang.org/x/term)** | Raw terminal mode for single-keypress confirmations |
+| **[stretchr/testify](https://github.com/stretchr/testify)** | `assert` and `require` in unit and integration tests |
+
+### How Dependencies Are Used
+
+```mermaid
+graph TD
+ CLI["OpenFrame CLI"] --> cobra["cobra\n(command routing)"]
+ CLI --> pterm["pterm\n(all terminal UI)"]
+ CLI --> promptui["promptui\n(select menus, text input)"]
+
+ ChartSvc["Chart Services"] --> clientgo["client-go\n(K8s API)"]
+ ChartSvc --> argocdclient["argo-cd client\n(application watch)"]
+ ChartSvc --> apiext["apiextensions\n(CRD checks)"]
+ ChartSvc --> dynamic["dynamic client\n(resource ops)"]
+ ChartSvc --> yamlsigs["sigs.k8s.io/yaml\n(K8s YAML)"]
+ ChartSvc --> yamlv3["gopkg.in/yaml.v3\n(helm values)"]
+
+ ClusterSvc["Cluster Service"] --> clientgo
+ ClusterSvc --> clientcmd["clientcmd\n(kubeconfig)"]
+
+ SharedUI["shared/ui"] --> pterm
+ SharedUI["shared/ui"] --> promptui
+ SharedUI["shared/ui"] --> term["golang.org/x/term\n(raw terminal)"]
+
+ Tests["Tests"] --> testify["testify\n(assertions)"]
+```
+
+---
+
+## CLI Commands
+
+### Command Reference
+
+| Command | Flags | Description |
+|---|---|---|
+| `openframe bootstrap [name]` | `--deployment-mode`, `--non-interactive`, `--verbose/-v` | Full environment setup: cluster create + chart install |
+| `openframe cluster create [name]` | `--type`, `--nodes/-n`, `--version`, `--skip-wizard`, `--dry-run` | Create a K3D cluster (interactive wizard or skip-wizard) |
+| `openframe cluster delete [name]` | `--force/-f` | Delete a cluster with confirmation |
+| `openframe cluster list` | `--quiet/-q`, `--verbose/-v` | List all managed clusters |
+| `openframe cluster status [name]` | `--detailed/-d`, `--no-apps` | Show cluster health, nodes, and ArgoCD apps |
+| `openframe cluster cleanup [name]` | `--force/-f` | Remove unused Docker images and resources |
+| `openframe chart install [name]` | `--deployment-mode`, `--non-interactive`, `--github-branch`, `--github-repo`, `--cert-dir`, `--force`, `--dry-run`, `--verbose` | Install ArgoCD + app-of-apps with optional wizard |
+| `openframe dev intercept [service]` | `--port`, `--namespace`, `--mount`, `--env-file`, `--global`, `--header`, `--replace`, `--remote-port` | Telepresence service intercept (interactive or flag-based) |
+| `openframe dev skaffold [cluster]` | `--port`, `--namespace`, `--image`, `--sync-local`, `--sync-remote`, `--skip-bootstrap`, `--helm-values` | Skaffold dev workflow with optional cluster bootstrap |
+
+### Deployment Modes
+
+| Mode Flag | Repository | Use Case |
+|---|---|---|
+| `oss-tenant` | `openframe-oss-tenant` | Default self-hosted OpenFrame deployment |
+| `saas-tenant` | `openframe-saas-tenant` | SaaS managed tenant deployment |
+| `saas-shared` | `openframe-saas-shared` | Shared SaaS infrastructure deployment |
+
+### Quick Start Examples
+
+```bash
+# Interactive full bootstrap
+openframe bootstrap
+
+# Non-interactive CI/CD bootstrap
+openframe bootstrap my-cluster --deployment-mode=oss-tenant --non-interactive
+
+# Create cluster then install charts separately
+openframe cluster create my-cluster --nodes 4 --skip-wizard
+openframe chart install my-cluster --deployment-mode=oss-tenant
+
+# Local development intercept
+openframe dev intercept my-service --port 8080 --namespace production
+
+# Skaffold dev workflow
+openframe dev skaffold my-dev-cluster
+```
+
+---
+
+## Community & Support
+
+> **Support happens in Slack, not GitHub Issues.**
+
+- **OpenMSP Slack**: [Join the community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)
+- **Website**: [https://flamingo.run](https://flamingo.run)
+- **OpenFrame Platform**: [https://openframe.ai](https://openframe.ai)
diff --git a/internal/chart/providers/argocd/.applications.md b/internal/chart/providers/argocd/.applications.md
index 47096c92..f24f01dc 100644
--- a/internal/chart/providers/argocd/.applications.md
+++ b/internal/chart/providers/argocd/.applications.md
@@ -1,48 +1,39 @@
-
-This Go file provides ArgoCD application management functionality with support for both native Kubernetes API clients and kubectl fallback operations, specifically designed for k3d cluster environments.
+
+Manages ArgoCD application state and Kubernetes client initialization for the OpenFrame CLI, providing both native Go client and `kubectl`-based access to ArgoCD resources.
## Key Components
-### Manager Struct
-- **Manager**: Primary ArgoCD manager with command executor and multiple Kubernetes client interfaces
-- **NewManager()**: Basic constructor with command executor
-- **NewManagerWithCluster()**: Constructor with explicit cluster context
-- **NewManagerWithConfig()**: Preferred constructor with pre-configured Kubernetes client
+### Types
-### Application Types
-- **Application**: Represents ArgoCD application status with health, sync, and operational details
-- **argoApp/argoAppList**: Internal JSON parsing structures for kubectl output
+- **`Manager`** — Core struct holding the command executor, cluster context, native Kubernetes/ArgoCD clients, and stabilization check configuration
+- **`Application`** — Represents a parsed ArgoCD application status (health, sync, conditions, operation state, source info)
+- **`argoAppList` / `argoApp`** — Internal JSON parsing structs for `kubectl` output
-### Core Methods
-- **initKubernetesClients()**: Lazy initialization of native Kubernetes clients with TLS bypass for local clusters
-- **getTotalExpectedApplications()**: Determines expected application count using native clients or kubectl fallback
-- **parseApplications()**: Retrieves ArgoCD application status (implementation appears truncated)
+### Constructors
-## Usage Example
+- **`NewManager`** — Basic manager from an executor
+- **`NewManagerWithCluster`** — Manager with explicit k3d cluster context
+- **`NewManagerWithConfig`** — Preferred constructor when a `*rest.Config` is already available; initializes all native clients immediately with insecure TLS applied
-```go
-import (
- "context"
- "github.com/flamingo-stack/openframe-cli/internal/shared/executor"
-)
+### Methods
-// Basic usage with command executor
-exec := executor.NewCommandExecutor()
-manager := argocd.NewManager(exec)
+- **`initKubernetesClients()`** — Lazy initializer for native Kubernetes, API extensions, and ArgoCD clients; handles Windows `host.docker.internal` → `127.0.0.1` normalization
+- **`getTotalExpectedApplications()`** — Determines expected application count via native client (primary) or falls back to kubectl on Windows/WSL2
+- **`getTotalExpectedApplicationsViaKubectl()`** — kubectl fallback using jsonpath and JSON output to count ArgoCD applications
+- **`getKubectlArgs()`** — Injects `--context k3d-` into kubectl calls when a cluster name is set
-// Usage with specific cluster context
-manager = argocd.NewManagerWithCluster(exec, "openframe")
+## Usage Example
-// Usage with pre-configured Kubernetes config (preferred)
-manager, err := argocd.NewManagerWithConfig(exec, kubeConfig)
+```go
+// Preferred: use when rest.Config is already available
+mgr, err := argocd.NewManagerWithConfig(exec, restConfig)
if err != nil {
log.Fatal(err)
}
-// Get total expected applications
-ctx := context.Background()
-count := manager.getTotalExpectedApplications(ctx, config)
-fmt.Printf("Expected applications: %d\n", count)
-```
+// Or use with explicit cluster name (kubectl-based)
+mgr := argocd.NewManagerWithCluster(exec, "openframe")
-The manager includes Windows-specific handling for k3d clusters and provides both native Kubernetes API access and kubectl command fallbacks for reliability across different environments.
\ No newline at end of file
+// Count expected applications before waiting for readiness
+total := mgr.getTotalExpectedApplications(ctx, chartConfig)
+```
\ No newline at end of file
diff --git a/internal/chart/providers/argocd/.argocd_values.md b/internal/chart/providers/argocd/.argocd_values.md
index 9c1233df..b78a7374 100644
--- a/internal/chart/providers/argocd/.argocd_values.md
+++ b/internal/chart/providers/argocd/.argocd_values.md
@@ -1,46 +1,34 @@
-
-Provides pre-configured Helm chart values for ArgoCD deployment with optimized resource allocation and monitoring integration.
+
+Provides the ArgoCD Helm chart values configuration as a Go string, used for deploying ArgoCD with predefined resource limits, health checks, and Loki logging annotations.
## Key Components
-- **GetArgoCDValues()** - Returns a complete YAML configuration string for ArgoCD Helm chart deployment
-
-## Configuration Features
-
-The returned YAML includes:
-
-- **Custom Health Checks** - Application health status monitoring via Lua script
-- **Resource Limits** - CPU and memory constraints for all ArgoCD components
-- **Loki Integration** - Pod annotations for log scraping (`loki.grafana.com/scrape: "true"`)
-- **Extended Timeouts** - Controller sync timeout (1800s) and repo server exec timeout (180s)
-- **Component Scaling** - Optimized resource requests/limits for controller, server, repo server, Redis, Dex, ApplicationSet, and notifications
+- **`GetArgoCDValues() string`** — Returns a YAML string containing the full ArgoCD Helm chart values, including:
+ - Custom health check logic for `argoproj.io/Application` resources (Lua script)
+ - Sync timeout set to 1800 seconds
+ - Loki scrape annotations on `controller`, `server`, and `repoServer` pods
+ - Resource requests/limits for all ArgoCD components
+ - `ARGOCD_EXEC_TIMEOUT` set to `180s` on the repo server
+
+## Component Resource Summary
+
+| Component | CPU Request | CPU Limit | Memory Request | Memory Limit |
+|---|---|---|---|---|
+| `controller` | 200m | 400m | 800Mi | 1Gi |
+| `server` | 200m | 300m | 400Mi | 600Mi |
+| `repoServer` | 200m | 400m | 400Mi | 800Mi |
+| `redis` | 50m | 100m | 64Mi | 128Mi |
+| `dex` | 50m | 100m | 64Mi | 128Mi |
+| `applicationSet` | 50m | 100m | 64Mi | 128Mi |
+| `notifications` | 50m | 100m | 64Mi | 128Mi |
## Usage Example
```go
-package main
-
-import (
- "fmt"
- "github.com/your-org/your-project/argocd"
-)
-
-func main() {
- // Get ArgoCD Helm values for deployment
- values := argocd.GetArgoCDValues()
-
- // Write to values.yaml file for Helm deployment
- err := os.WriteFile("argocd-values.yaml", []byte(values), 0644)
- if err != nil {
- log.Fatal(err)
- }
-
- // Or use directly with Helm Go SDK
- fmt.Println("ArgoCD values configured with:")
- fmt.Println("- Resource limits for all components")
- fmt.Println("- Loki scraping enabled")
- fmt.Println("- Custom health checks")
-}
-```
-
-The configuration optimizes ArgoCD for production use with appropriate resource constraints and observability features.
\ No newline at end of file
+import "github.com/your-org/your-repo/argocd"
+
+values := argocd.GetArgoCDValues()
+
+// Pass to Helm install
+helmClient.Install("argocd", "argo/argo-cd", values)
+```
\ No newline at end of file
diff --git a/internal/chart/providers/argocd/.wait.md b/internal/chart/providers/argocd/.wait.md
index 8dd7d7ef..c33dd54b 100644
--- a/internal/chart/providers/argocd/.wait.md
+++ b/internal/chart/providers/argocd/.wait.md
@@ -1,41 +1,34 @@
-
-This file provides ArgoCD application monitoring and synchronization logic for OpenFrame CLI deployments.
+
+Monitors and waits for all ArgoCD applications to reach a healthy and synced state during OpenFrame chart installation, with resilience for cluster connectivity issues, Windows/WSL environments, and repo-server recovery.
## Key Components
-- **WaitForApplications()** - Main function that waits for all ArgoCD applications to reach Healthy and Synced status
-- **Context Management** - Handles cancellation signals, timeouts, and graceful shutdown via signal handlers
-- **Health Monitoring** - Periodic cluster connectivity checks and resource monitoring during bootstrap and main phases
-- **Progress Tracking** - Visual spinner with timer and verbose logging for application synchronization progress
-- **Recovery Logic** - WSL-specific recovery mechanisms and repo-server issue detection/recovery
-- **Timeout Handling** - 60-minute timeout with early exit conditions for dry-run mode and cancelled contexts
+- **`WaitForApplications(ctx, config)`** — Main entry point. Orchestrates the full wait lifecycle including dry-run bypass, context deadline checks, signal handling, bootstrap phase, and main monitoring loop.
+- **Bootstrap phase** — 30-second initial wait with 5-second cluster health checks before beginning application polling.
+- **Main monitoring loop** — Polls ArgoCD application state every 2 seconds with a 60-minute timeout, tracking `everReadyApps` to tolerate transient out-of-sync states.
+- **Cluster connectivity checks** — Periodic health checks with exponential backoff (`consecutiveFailures` up to `maxConsecutiveFailures = 5`), WSL recovery via `executor.TryRecoverWSL()` on Windows.
+- **Repo-server recovery** — Tracks per-app repo-server failures (`appsWithRepoServerIssues`), proactively triggers `triggerRepoServerRecovery` on resource-type issues, with configurable retry limits.
+- **Spinner management** — Thread-safe pterm spinner using `spinnerMutex`; gracefully stops on context cancellation, interrupt signals, or function exit.
+- **Signal handling** — Listens for `os.Interrupt` / `syscall.SIGTERM` via a goroutine-backed local context derived from the parent context.
## Usage Example
```go
-// Initialize ArgoCD manager
-manager := &Manager{
- clusterName: "my-cluster",
-}
+manager := argocd.NewManager(kubeClient, dynamicClient)
+manager.StabilizationChecks = 15 // 15 × 2s = 30s stable window
-// Configure installation
-config := config.ChartInstallConfig{
- ClusterName: "my-cluster",
+cfg := config.ChartInstallConfig{
+ ClusterName: "openframe-local",
Verbose: true,
- DryRun: false,
Silent: false,
+ DryRun: false,
SkipCRDs: false,
}
-// Wait for applications with context timeout
-ctx, cancel := context.WithTimeout(context.Background(), 60*time.Minute)
+ctx, cancel := context.WithTimeout(context.Background(), 90*time.Minute)
defer cancel()
-// Monitor ArgoCD application synchronization
-err := manager.WaitForApplications(ctx, config)
-if err != nil {
- log.Fatalf("Failed to wait for ArgoCD applications: %v", err)
+if err := manager.WaitForApplications(ctx, cfg); err != nil {
+ log.Fatalf("ArgoCD sync failed: %v", err)
}
-```
-
-The function includes comprehensive error handling for cluster connectivity issues, WSL recovery on Windows systems, and graceful handling of interrupt signals during long-running synchronization operations.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/internal/chart/providers/helm/.manager.md b/internal/chart/providers/helm/.manager.md
index a21dbb18..0bfd979b 100644
--- a/internal/chart/providers/helm/.manager.md
+++ b/internal/chart/providers/helm/.manager.md
@@ -1,48 +1,59 @@
-
-A comprehensive Helm operations manager for OpenFrame that handles chart installations, Kubernetes cluster operations, and ArgoCD deployment with support for both Windows and Linux environments.
+
+Manages Helm operations for installing and configuring charts (primarily ArgoCD) within Kubernetes clusters, including client initialization, CRD handling, and progress reporting.
## Key Components
-- **HelmManager**: Main struct containing Kubernetes clients and command executor
-- **NewHelmManager()**: Constructor that initializes Kubernetes clients with TLS bypass for local clusters
-- **IsHelmInstalled()**: Verifies Helm CLI availability
-- **IsChartInstalled()**: Checks if a Helm release exists in a namespace
-- **InstallArgoCD()**: Core ArgoCD installation with Helm
-- **InstallArgoCDWithProgress()**: ArgoCD installation with progress indicators and cluster connectivity verification
-- **getHelmEnv()**: Platform-specific environment configuration for Helm directories
+### `HelmManager` struct
+Core struct holding:
+- `executor` — command runner for `helm`/`kubectl` CLI calls
+- `kubeConfig` — cluster connection config (`rest.Config`)
+- `dynamicClient` — dynamic Kubernetes client for programmatic resource management
+- `kubeClient` — typed client for Deployment checks
+- `crdClient` — client for CRD existence checks
+- `verbose` — enables debug logging
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `NewHelmManager` | Constructs `HelmManager`; gracefully degrades if clients fail to initialize |
+| `getHelmEnv` | Returns writable Helm env vars (`HELM_CACHE_HOME`, etc.); creates dirs on non-Windows |
+| `IsHelmInstalled` | Verifies `helm` binary is available via `helm version --short` |
+| `IsChartInstalled` | Checks if a named release exists in a given namespace |
+| `InstallArgoCD` | Installs ArgoCD via `helm upgrade --install`; handles Windows→WSL path conversion |
+| `InstallArgoCDWithProgress` | Wraps `InstallArgoCD` with spinner UI, cluster readiness retries, and CRD pre-installation |
## Usage Example
```go
-// Initialize Helm manager with Kubernetes config
-config, err := rest.InClusterConfig()
-if err != nil {
- return err
-}
+import (
+ "context"
+ "github.com/flamingo-stack/openframe-cli/internal/chart/helm"
+ "github.com/flamingo-stack/openframe-cli/internal/chart/utils/config"
+ "github.com/flamingo-stack/openframe-cli/internal/shared/executor"
+)
+
+exec := executor.NewDefaultExecutor()
+restConfig, _ := clientcmd.BuildConfigFromFlags("", kubeConfigPath)
-executor := executor.NewCommandExecutor()
-helmManager, err := NewHelmManager(executor, config, true)
+manager, err := helm.NewHelmManager(exec, restConfig, true)
if err != nil {
- return err
+ log.Fatal(err)
}
-// Check if Helm is available
ctx := context.Background()
-if err := helmManager.IsHelmInstalled(ctx); err != nil {
- return fmt.Errorf("helm not available: %w", err)
-}
-// Install ArgoCD with configuration
-installConfig := config.ChartInstallConfig{
- ClusterName: "my-cluster",
- DryRun: false,
- Verbose: true,
+if err := manager.IsHelmInstalled(ctx); err != nil {
+ log.Fatal("helm not found")
}
-err = helmManager.InstallArgoCDWithProgress(ctx, installConfig)
-if err != nil {
- return fmt.Errorf("argocd installation failed: %w", err)
-}
+err = manager.InstallArgoCDWithProgress(ctx, config.ChartInstallConfig{
+ ClusterName: "openframe",
+ Verbose: true,
+ Silent: false,
+ NonInteractive: false,
+ SkipCRDs: false,
+})
```
-The manager provides robust error handling, platform compatibility (Windows/WSL support), and comprehensive logging for Helm operations within the OpenFrame ecosystem.
\ No newline at end of file
+> **Note:** On Windows, `HelmManager` automatically converts temp file paths to WSL-compatible paths and appends the `k3d-` kube context to all Helm commands. TLS verification is bypassed for local k3d clusters via `ApplyInsecureTLSConfig`, preserving client certificate authentication.
\ No newline at end of file
+