docs: add comprehensive documentation for sunbeam CLI

docs/api-reference.md

@@ -0,0 +1,518 @@
+---
+layout: default
+title: API Reference
+description: Comprehensive API documentation for all Sunbeam modules
+parent: index
+toc: true
+---
+
+# API Reference
+
+This section provides comprehensive API documentation for all Sunbeam modules, including function signatures, parameters, return values, and usage examples.
+
+## CLI Module (`sunbeam.cli`)
+
+### Main Function
+
+```python
+def main() -> None
+```
+
+**Description:** Main entry point for the Sunbeam CLI. Parses arguments and dispatches to appropriate command handlers.
+
+**Environment Variables:**
+- `SUNBEAM_SSH_HOST`: Required for production environment
+
+**Global Arguments:**
+- `--env`: Target environment (`local` or `production`)
+- `--context`: kubectl context override
+- `--domain`: Domain suffix for production
+- `--email`: ACME email for cert-manager
+
+### Command Dispatch
+
+The main function uses a dispatch pattern to route commands to their handlers:
+
+```python
+# Example dispatch pattern
+if args.verb == "up":
+    from sunbeam.cluster import cmd_up
+    cmd_up()
+elif args.verb == "status":
+    from sunbeam.services import cmd_status
+    cmd_status(args.target)
+# ... additional commands
+```
+
+## Kubernetes Module (`sunbeam.kube`)
+
+### Context Management
+
+```python
+def set_context(ctx: str, ssh_host: str = "") -> None
+```
+
+**Parameters:**
+- `ctx`: Kubernetes context name
+- `ssh_host`: SSH host for production tunnel (optional)
+
+**Description:** Sets the active kubectl context and SSH host for production environments.
+
+```python
+def context_arg() -> str
+```
+
+**Returns:** `--context=<active>` string for subprocess calls
+
+### Kubernetes Operations
+
+```python
+def kube(*args, input=None, check=True) -> subprocess.CompletedProcess
+```
+
+**Parameters:**
+- `*args`: kubectl arguments
+- `input`: stdin input (optional)
+- `check`: Whether to raise exception on non-zero exit (default: True)
+
+**Returns:** CompletedProcess result
+
+**Description:** Run kubectl against active context with automatic SSH tunnel management.
+
+```python
+def kube_out(*args) -> str
+```
+
+**Parameters:**
+- `*args`: kubectl arguments
+
+**Returns:** stdout output (empty string on failure)
+
+```python
+def kube_ok(*args) -> bool
+```
+
+**Parameters:**
+- `*args`: kubectl arguments
+
+**Returns:** True if command succeeds
+
+```python
+def kube_apply(manifest: str, *, server_side: bool = True) -> None
+```
+
+**Parameters:**
+- `manifest`: YAML manifest string
+- `server_side`: Use server-side apply (default: True)
+
+**Description:** Apply YAML manifest via kubectl.
+
+### Resource Management
+
+```python
+def ns_exists(ns: str) -> bool
+```
+
+**Parameters:**
+- `ns`: Namespace name
+
+**Returns:** True if namespace exists
+
+```python
+def ensure_ns(ns: str) -> None
+```
+
+**Parameters:**
+- `ns`: Namespace name
+
+**Description:** Ensure namespace exists, creating if necessary.
+
+```python
+def create_secret(ns: str, name: str, **literals) -> None
+```
+
+**Parameters:**
+- `ns`: Namespace name
+- `name`: Secret name
+- `**literals`: Key-value pairs for secret data
+
+**Description:** Create or update Kubernetes secret idempotently.
+
+### Kustomize Integration
+
+```python
+def kustomize_build(overlay: Path, domain: str, email: str = "") -> str
+```
+
+**Parameters:**
+- `overlay`: Path to kustomize overlay directory
+- `domain`: Domain suffix for substitution
+- `email`: ACME email for substitution (optional)
+
+**Returns:** Built manifest YAML with substitutions applied
+
+**Description:** Build kustomize overlay with domain/email substitution and helm support.
+
+### SSH Tunnel Management
+
+```python
+def ensure_tunnel() -> None
+```
+
+**Description:** Open SSH tunnel to production cluster if needed. Automatically checks if tunnel is already open.
+
+### Utility Functions
+
+```python
+def parse_target(s: str | None) -> tuple[str | None, str | None]
+```
+
+**Parameters:**
+- `s`: Target string in format `namespace/name` or `namespace`
+
+**Returns:** Tuple of (namespace, name)
+
+**Examples:**
+```python
+parse_target("ory/kratos")    # ("ory", "kratos")
+parse_target("lasuite")       # ("lasuite", None)
+parse_target(None)             # (None, None)
+```
+
+```python
+def domain_replace(text: str, domain: str) -> str
+```
+
+**Parameters:**
+- `text`: Input text containing DOMAIN_SUFFIX placeholders
+- `domain`: Domain to substitute
+
+**Returns:** Text with DOMAIN_SUFFIX replaced by domain
+
+```python
+def get_lima_ip() -> str
+```
+
+**Returns:** IP address of Lima VM
+
+**Description:** Discover Lima VM IP using multiple fallback methods.
+
+```python
+def get_domain() -> str
+```
+
+**Returns:** Active domain from cluster state
+
+**Description:** Discover domain from various cluster sources with fallback to Lima IP.
+
+### Command Functions
+
+```python
+def cmd_k8s(kubectl_args: list[str]) -> int
+```
+
+**Parameters:**
+- `kubectl_args`: Arguments to pass to kubectl
+
+**Returns:** Exit code
+
+**Description:** Transparent kubectl passthrough for active context.
+
+```python
+def cmd_bao(bao_args: list[str]) -> int
+```
+
+**Parameters:**
+- `bao_args`: Arguments to pass to bao CLI
+
+**Returns:** Exit code
+
+**Description:** Run bao CLI inside OpenBao pod with root token injection.
+
+## Manifests Module (`sunbeam.manifests`)
+
+### Main Command
+
+```python
+def cmd_apply(env: str = "local", domain: str = "", email: str = "", namespace: str = "") -> None
+```
+
+**Parameters:**
+- `env`: Environment (`local` or `production`)
+- `domain`: Domain suffix (required for production)
+- `email`: ACME email for cert-manager
+- `namespace`: Limit apply to specific namespace (optional)
+
+**Description:** Build kustomize overlay, apply domain/email substitution, and apply manifests with convergence handling.
+
+### Cleanup Functions
+
+```python
+def pre_apply_cleanup(namespaces=None) -> None
+```
+
+**Parameters:**
+- `namespaces`: List of namespaces to clean (default: all managed namespaces)
+
+**Description:** Clean up immutable resources and stale secrets before apply.
+
+### ConfigMap Management
+
+```python
+def _snapshot_configmaps() -> dict
+```
+
+**Returns:** Dictionary of `{ns/name: resourceVersion}` for all ConfigMaps
+
+```python
+def _restart_for_changed_configmaps(before: dict, after: dict) -> None
+```
+
+**Parameters:**
+- `before`: ConfigMap snapshot before apply
+- `after`: ConfigMap snapshot after apply
+
+**Description:** Restart deployments that mount changed ConfigMaps.
+
+### Webhook Management
+
+```python
+def _wait_for_webhook(ns: str, svc: str, timeout: int = 120) -> bool
+```
+
+**Parameters:**
+- `ns`: Namespace of webhook service
+- `svc`: Service name
+- `timeout`: Maximum wait time in seconds
+
+**Returns:** True if webhook becomes ready
+
+**Description:** Wait for webhook service endpoint to become available.
+
+### Utility Functions
+
+```python
+def _filter_by_namespace(manifests: str, namespace: str) -> str
+```
+
+**Parameters:**
+- `manifests`: Multi-document YAML string
+- `namespace`: Namespace to filter by
+
+**Returns:** Filtered YAML containing only resources for specified namespace
+
+**Description:** Filter manifests by namespace using string matching.
+
+## Services Module (`sunbeam.services`)
+
+### Status Command
+
+```python
+def cmd_status(target: str | None) -> None
+```
+
+**Parameters:**
+- `target`: Optional target in format `namespace` or `namespace/name`
+
+**Description:** Show pod health across managed namespaces with VSO sync status.
+
+### Log Command
+
+```python
+def cmd_logs(target: str, follow: bool) -> None
+```
+
+**Parameters:**
+- `target`: Target in format `namespace/name`
+- `follow`: Whether to stream logs
+
+**Description:** Stream logs for a service using label-based pod selection.
+
+### Get Command
+
+```python
+def cmd_get(target: str, output: str = "yaml") -> None
+```
+
+**Parameters:**
+- `target`: Target in format `namespace/name`
+- `output`: Output format (`yaml`, `json`, or `wide`)
+
+**Description:** Get raw kubectl output for a resource.
+
+### Restart Command
+
+```python
+def cmd_restart(target: str | None) -> None
+```
+
+**Parameters:**
+- `target`: Optional target in format `namespace` or `namespace/name`
+
+**Description:** Rolling restart of services. If no target, restarts all managed services.
+
+### VSO Sync Status
+
+```python
+def _vso_sync_status() -> None
+```
+
+**Description:** Print VaultStaticSecret and VaultDynamicSecret sync health status.
+
+## Tools Module (`sunbeam.tools`)
+
+### Tool Management
+
+```python
+def ensure_tool(name: str) -> Path
+```
+
+**Parameters:**
+- `name`: Tool name (must be in TOOLS dictionary)
+
+**Returns:** Path to executable
+
+**Raises:**
+- `ValueError`: Unknown tool
+- `RuntimeError`: SHA256 verification failure
+
+**Description:** Ensure tool is available, downloading and verifying if necessary.
+
+```python
+def run_tool(name: str, *args, **kwargs) -> subprocess.CompletedProcess
+```
+
+**Parameters:**
+- `name`: Tool name
+- `*args`: Arguments to pass to tool
+- `**kwargs`: Additional subprocess.run parameters
+
+**Returns:** CompletedProcess result
+
+**Description:** Run tool, ensuring it's downloaded first. Handles PATH setup for kustomize/helm integration.
+
+### Internal Utilities
+
+```python
+def _sha256(path: Path) -> str
+```
+
+**Parameters:**
+- `path`: Path to file
+
+**Returns:** SHA256 hash of file contents
+
+**Description:** Calculate SHA256 hash (internal utility).
+
+## Output Module (`sunbeam.output`)
+
+### Output Functions
+
+```python
+def step(msg: str) -> None
+```
+
+**Parameters:**
+- `msg`: Message to display
+
+**Description:** Print step header with `==>` prefix.
+
+```python
+def ok(msg: str) -> None
+```
+
+**Parameters:**
+- `msg`: Message to display
+
+**Description:** Print success/info message with indentation.
+
+```python
+def warn(msg: str) -> None
+```
+
+**Parameters:**
+- `msg`: Warning message
+
+**Description:** Print warning to stderr.
+
+```python
+def die(msg: str) -> None
+```
+
+**Parameters:**
+- `msg`: Error message
+
+**Description:** Print error to stderr and exit with code 1.
+
+```python
+def table(rows: list[list[str]], headers: list[str]) -> str
+```
+
+**Parameters:**
+- `rows`: List of row data
+- `headers`: List of column headers
+
+**Returns:** Formatted table string
+
+**Description:** Generate aligned text table with automatic column sizing.
+
+## Usage Patterns
+
+### Typical Command Flow
+
+```python
+# CLI entry point
+from sunbeam.cli import main
+main()
+
+# Module usage example
+from sunbeam.kube import kube, kube_out, set_context
+from sunbeam.output import step, ok, warn
+
+# Set context
+set_context("sunbeam")
+
+# Check cluster status
+step("Checking cluster status...")
+if kube_ok("get", "nodes"):
+    ok("Cluster is ready")
+    node_count = kube_out("get", "nodes", "--no-headers").count("\n") + 1
+    ok(f"Found {node_count} nodes")
+else:
+    warn("Cluster not ready")
+```
+
+### Error Handling Pattern
+
+```python
+from sunbeam.output import step, ok, die
+from sunbeam.kube import kube_ok
+
+step("Validating cluster requirements...")
+
+# Check required components
+required = [
+    ("kube-system", "kube-dns"),
+    ("ingress-nginx", "ingress-nginx-controller")
+]
+
+for ns, deployment in required:
+    if not kube_ok("get", "deployment", deployment, "-n", ns):
+        die(f"Required deployment {ns}/{deployment} not found")
+
+ok("All requirements satisfied")
+```
+
+### Tool Usage Pattern
+
+```python
+from sunbeam.tools import ensure_tool, run_tool
+
+# Ensure kubectl is available
+kubectl_path = ensure_tool("kubectl")
+
+# Run kubectl command
+result = run_tool("kubectl", "get", "pods", "-A", 
+                  capture_output=True, text=True)
+print(result.stdout)
+```

docs/cli-reference.md

@@ -0,0 +1,254 @@
+---
+layout: default
+title: CLI Reference
+description: Complete command reference for Sunbeam CLI
+parent: index
+toc: true
+---
+
+# CLI Reference
+
+The Sunbeam CLI provides a comprehensive set of commands for managing local development environments.
+
+## Command Structure
+
+```bash
+sunbeam [global-options] <verb> [verb-options]
+```
+
+### Global Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--env` | Target environment (`local` or `production`) | `local` |
+| `--context` | kubectl context override | Auto-determined |
+| `--domain` | Domain suffix for production deploys | `` |
+| `--email` | ACME email for cert-manager | `` |
+
+## Commands
+
+### Cluster Management
+
+#### `sunbeam up`
+Bring up the full local cluster including Lima VM and Kubernetes.
+
+```bash
+sunbeam up
+```
+
+#### `sunbeam down`
+Tear down the Lima VM and local cluster.
+
+```bash
+sunbeam down
+```
+
+### Status and Information
+
+#### `sunbeam status [target]`
+Show pod health across all namespaces, optionally filtered.
+
+```bash
+# All pods
+sunbeam status
+
+# Specific namespace
+sunbeam status ory
+
+# Specific service
+sunbeam status ory/kratos
+```
+
+### Manifest Management
+
+#### `sunbeam apply [namespace]`
+Build kustomize overlay, apply domain substitution, and apply manifests.
+
+```bash
+# Apply all manifests
+sunbeam apply
+
+# Apply specific namespace only
+sunbeam apply lasuite
+
+# Production environment with custom domain
+sunbeam apply --env production --domain sunbeam.pt
+```
+
+### Service Operations
+
+#### `sunbeam logs <ns/name> [-f]`
+View logs for a service.
+
+```bash
+# View recent logs
+sunbeam logs ory/kratos
+
+# Stream logs
+sunbeam logs ory/kratos -f
+```
+
+#### `sunbeam get <ns/name> [-o yaml|json|wide]`
+Get raw kubectl output for a resource.
+
+```bash
+# Get pod details
+sunbeam get ory/kratos-abc -o yaml
+```
+
+#### `sunbeam restart [target]`
+Rolling restart of services.
+
+```bash
+# Restart all services
+sunbeam restart
+
+# Restart specific namespace
+sunbeam restart ory
+
+# Restart specific service
+sunbeam restart ory/kratos
+```
+
+#### `sunbeam check [target]`
+Run functional service health checks.
+
+```bash
+# Check all services
+sunbeam check
+
+# Check specific service
+sunbeam check ory/kratos
+```
+
+### Build and Deployment
+
+#### `sunbeam build <what> [--push] [--deploy]`
+Build artifacts and optionally push and deploy.
+
+```bash
+# Build proxy
+sunbeam build proxy
+
+# Build and push
+sunbeam build proxy --push
+
+# Build, push, and deploy
+sunbeam build proxy --deploy
+```
+
+Available build targets:
+- `proxy`, `integration`, `kratos-admin`, `meet`
+- `docs-frontend`, `people-frontend`, `people`
+
+#### `sunbeam mirror`
+Mirror amd64-only La Suite images.
+
+```bash
+sunbeam mirror
+```
+
+### Secret Management
+
+#### `sunbeam seed`
+Generate and store all credentials in OpenBao.
+
+```bash
+sunbeam seed
+```
+
+#### `sunbeam verify`
+End-to-end VSO + OpenBao integration test.
+
+```bash
+sunbeam verify
+```
+
+### Bootstrap Operations
+
+#### `sunbeam bootstrap`
+Create Gitea orgs/repos and set up Lima registry.
+
+```bash
+sunbeam bootstrap
+```
+
+### Kubernetes Operations
+
+#### `sunbeam k8s [kubectl args...]`
+Transparent kubectl passthrough.
+
+```bash
+# Any kubectl command
+sunbeam k8s get pods -A
+```
+
+#### `sunbeam bao [bao args...]`
+Run bao CLI inside OpenBao pod with root token.
+
+```bash
+# Run bao commands
+sunbeam bao secrets list
+```
+
+### User Management
+
+#### `sunbeam user list [--search email]`
+List identities.
+
+```bash
+# List all users
+sunbeam user list
+
+# Search by email
+sunbeam user list --search user@example.com
+```
+
+#### `sunbeam user get <target>`
+Get identity by email or ID.
+
+```bash
+sunbeam user get user@example.com
+```
+
+#### `sunbeam user create <email> [--name name] [--schema schema]`
+Create identity.
+
+```bash
+sunbeam user create user@example.com --name "User Name"
+```
+
+#### `sunbeam user delete <target>`
+Delete identity.
+
+```bash
+sunbeam user delete user@example.com
+```
+
+#### `sunbeam user recover <target>`
+Generate recovery link.
+
+```bash
+sunbeam user recover user@example.com
+```
+
+#### `sunbeam user disable <target>`
+Disable identity and revoke sessions.
+
+```bash
+sunbeam user disable user@example.com
+```
+
+#### `sunbeam user enable <target>`
+Re-enable a disabled identity.
+
+```bash
+sunbeam user enable user@example.com
+```
+
+#### `sunbeam user set-password <target> <password>`
+Set password for an identity.
+
+```bash
+sunbeam user set-password user@example.com newpassword
+```

docs/core-modules.md

@@ -0,0 +1,262 @@
+---
+layout: default
+title: Core Modules
+description: Detailed documentation of Sunbeam's core modules
+parent: index
+toc: true
+---
+
+# Core Modules
+
+Sunbeam's functionality is organized into several core modules, each responsible for specific aspects of cluster and service management.
+
+## Module Overview
+
+```mermaid
+graph TD
+    cli[CLI Entry Point] --> kube[Kubernetes Interface]
+    cli --> manifests[Manifest Management]
+    cli --> services[Service Operations]
+    cli --> secrets[Secret Management]
+    cli --> users[User Management]
+    cli --> images[Image Building]
+    cli --> cluster[Cluster Lifecycle]
+    cli --> tools[Tool Management]
+    cli --> output[Output Utilities]
+```
+
+## Kubernetes Interface (`sunbeam.kube`)
+
+The Kubernetes interface module provides core functionality for interacting with Kubernetes clusters.
+
+### Key Functions
+
+#### `set_context(ctx: str, ssh_host: str = "")`
+Set the active kubectl context and optional SSH host for production tunnels.
+
+#### `kube(*args, input=None, check=True)`
+Run kubectl commands against the active context with automatic SSH tunnel management.
+
+#### `kube_out(*args) -> str`
+Run kubectl and return stdout.
+
+#### `kube_ok(*args) -> bool`
+Return True if kubectl command succeeds.
+
+#### `kube_apply(manifest: str, server_side: bool = True)`
+Apply YAML manifest via kubectl.
+
+#### `kustomize_build(overlay: Path, domain: str, email: str = "") -> str`
+Build kustomize overlay with domain/email substitution.
+
+### Environment Management
+
+- **Local Development**: Uses Lima VM with context `sunbeam`
+- **Production**: Supports SSH tunneling to remote clusters
+- **Domain Handling**: Automatic domain discovery and substitution
+
+### SSH Tunnel Management
+
+The module automatically manages SSH tunnels for production environments:
+
+```python
+# Automatic tunnel opening when needed
+def ensure_tunnel():
+    # Check if tunnel is already open
+    # Open SSH tunnel if needed
+    # Verify tunnel is working
+```
+
+## Manifest Management (`sunbeam.manifests`)
+
+Handles kustomize-based manifest building, application, and lifecycle management.
+
+### Key Functions
+
+#### `cmd_apply(env: str = "local", domain: str = "", email: str = "", namespace: str = "")`
+Main entry point for manifest application:
+
+1. **Pre-apply Cleanup**: Remove immutable resources and stale secrets
+2. **ConfigMap Snapshotting**: Track ConfigMap versions for restart detection
+3. **Kustomize Build**: Build overlay with domain/email substitution
+4. **Namespace Filtering**: Apply only specific namespaces if requested
+5. **Webhook Waiting**: Wait for cert-manager webhook before convergence
+6. **ConfigMap Change Detection**: Restart deployments when ConfigMaps change
+
+#### `pre_apply_cleanup(namespaces=None)`
+Clean up resources that must be recreated:
+- Delete completed Jobs
+- Remove test Pods
+- Prune stale VaultStaticSecrets
+
+#### `_wait_for_webhook(ns: str, svc: str, timeout: int = 120) -> bool`
+Wait for webhook services to become ready.
+
+#### `_restart_for_changed_configmaps(before: dict, after: dict)`
+Restart deployments when mounted ConfigMaps change.
+
+### Manifest Processing Flow
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Pre-apply Cleanup]
+    B --> C[Snapshot ConfigMaps]
+    C --> D[Build Kustomize Overlay]
+    D --> E[Apply Domain/Email Substitution]
+    E --> F[First Apply Pass]
+    F --> G{Webhook Present?}
+    G -->|Yes| H[Wait for Webhook]
+    H --> I[Convergence Pass]
+    G -->|No| I
+    I --> J[Detect ConfigMap Changes]
+    J --> K[Restart Affected Deployments]
+    K --> L[Complete]
+```
+
+## Service Operations (`sunbeam.services`)
+
+Provides service management capabilities including status checks, log viewing, and restarts.
+
+### Key Functions
+
+#### `cmd_status(target: str | None)`
+Show pod health across managed namespaces:
+- Filter by namespace or namespace/service
+- Color-coded status indicators
+- VSO secret sync status
+
+#### `cmd_logs(target: str, follow: bool)`
+Stream logs for a service:
+- Automatic pod selection via labels
+- Follow mode for real-time logging
+
+#### `cmd_get(target: str, output: str = "yaml")`
+Get raw kubectl output for resources.
+
+#### `cmd_restart(target: str | None)`
+Rolling restart of services:
+- Restart all, by namespace, or specific service
+- Uses predefined service list
+
+### Managed Namespaces
+
+```
+["data", "devtools", "ingress", "lasuite", "media", "ory", "storage", "vault-secrets-operator"]
+```
+
+### Service Health Monitoring
+
+The status command provides comprehensive health monitoring:
+
+- **Pod Status**: Running, Completed, Failed, Pending
+- **Readiness**: Container ready ratios
+- **VSO Sync**: VaultStaticSecret and VaultDynamicSecret synchronization
+
+## Secret Management (`sunbeam.secrets`)
+
+Handles credential generation and OpenBao integration.
+
+### Key Functions
+
+#### `cmd_seed()`
+Generate and store all credentials in OpenBao.
+
+#### `cmd_verify()`
+End-to-end VSO + OpenBao integration test.
+
+### OpenBao Integration
+
+- **Root Token Management**: Automatic injection into bao commands
+- **Secret Generation**: Comprehensive credential seeding
+- **Integration Testing**: Verify VSO-OpenBao connectivity
+
+## User Management (`sunbeam.users`)
+
+Provides identity management for development environments.
+
+### Key Functions
+
+#### User Operations
+- `cmd_user_list(search: str)` - List identities
+- `cmd_user_get(target: str)` - Get identity details
+- `cmd_user_create(email: str, name: str, schema_id: str)` - Create identity
+- `cmd_user_delete(target: str)` - Delete identity
+- `cmd_user_recover(target: str)` - Generate recovery link
+- `cmd_user_disable(target: str)` - Disable identity
+- `cmd_user_enable(target: str)` - Enable identity
+- `cmd_user_set_password(target: str, password: str)` - Set password
+
+### Identity Management
+
+- Email-based identity lookup
+- Schema-based identity creation
+- Session management and recovery
+- Password management
+
+## Image Building (`sunbeam.images`)
+
+Handles container image building, pushing, and deployment.
+
+### Key Functions
+
+#### `cmd_build(what: str, push: bool, deploy: bool)`
+Build Docker images with optional push and deploy:
+
+- **Build Targets**: proxy, integration, kratos-admin, meet, frontend apps
+- **Push Integration**: Automatic registry pushing
+- **Deploy Integration**: Manifest application and rollout
+
+#### `cmd_mirror()`
+Mirror amd64-only La Suite images for ARM compatibility.
+
+## Cluster Management (`sunbeam.cluster`)
+
+Handles cluster lifecycle operations.
+
+### Key Functions
+
+#### `cmd_up()`
+Bring up the full local cluster including Lima VM.
+
+#### `cmd_down()`
+Tear down the Lima VM and cluster.
+
+## Tool Management (`sunbeam.tools`)
+
+Automatic binary management for required tools.
+
+### Key Features
+
+- **Binary Caching**: Download and cache kubectl, kustomize, helm
+- **SHA256 Verification**: Security verification of downloaded binaries
+- **Version Pinning**: Specific versions for reproducibility
+- **Automatic Updates**: Re-download when versions change
+
+### Supported Tools
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| kubectl | v1.32.2 | Kubernetes CLI |
+| kustomize | v5.8.1 | Manifest customization |
+| helm | v4.1.0 | Helm chart management |
+
+## Output Utilities (`sunbeam.output`)
+
+Consistent output formatting and user feedback.
+
+### Functions
+
+- `step(msg: str)` - Step headers
+- `ok(msg: str)` - Success messages
+- `warn(msg: str)` - Warnings
+- `die(msg: str)` - Error messages with exit
+- `table(rows: list, headers: list)` - Formatted tables
+
+### Output Style Guide
+
+```python
+step("Starting cluster...")  # ==> Starting cluster...
+ok("Cluster ready")          #     Cluster ready
+warn("Low memory")          #     WARN: Low memory
+die("Failed to start")      # ERROR: Failed to start (exits)
+```

docs/index.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Sunbeam CLI Documentation
+description: Comprehensive documentation for the Sunbeam local dev stack manager
+toc: true
+---
+
+# Sunbeam CLI Documentation
+
+Welcome to the comprehensive documentation for **Sunbeam CLI** - a powerful local development stack manager for Kubernetes-based applications.
+
+## Overview
+
+Sunbeam is a command-line tool designed to simplify the management of local development environments for Kubernetes applications. It provides a comprehensive suite of commands to handle cluster operations, service management, secret handling, and more.
+
+## Key Features
+
+- **Cluster Management**: Bring up and tear down local Kubernetes clusters
+- **Service Operations**: Manage services, logs, and health checks
+- **Secret Management**: Secure credential handling with OpenBao integration
+- **Manifest Management**: Kustomize-based manifest application with domain substitution
+- **User Management**: Identity management for development environments
+- **Tool Bundling**: Automatic download and management of required binaries
+
+## Getting Started
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/sunbeam.git
+cd sunbeam/cli
+
+# Install dependencies
+pip install .
+
+# Verify installation
+sunbeam --help
+```
+
+### Basic Usage
+
+```bash
+# Start your local cluster
+sunbeam up
+
+# Check cluster status
+sunbeam status
+
+# Apply manifests
+sunbeam apply
+
+# View service logs
+sunbeam logs ory/kratos
+```
+
+## Documentation Structure
+
+- **[CLI Reference](cli-reference)**: Complete command reference
+- **[Core Modules](core-modules)**: Detailed module documentation
+- **[Architecture](architecture)**: System architecture and design
+- **[Usage Examples](usage-examples)**: Practical usage scenarios
+- **[Development Guide](development)**: Contributing and extending Sunbeam
+
+## Support
+
+For issues, questions, or contributions, please refer to the [GitHub repository](https://github.com/your-org/sunbeam).

docs/usage-examples.md

@@ -0,0 +1,486 @@
+---
+layout: default
+title: Usage Examples
+description: Practical usage examples and best practices for Sunbeam CLI
+parent: index
+toc: true
+---
+
+# Usage Examples and Best Practices
+
+This section provides practical usage examples and best practices for working with Sunbeam CLI.
+
+## Common Workflows
+
+### Starting a New Development Session
+
+```bash
+# Start the local cluster
+sunbeam up
+
+# Check cluster status
+sunbeam status
+
+# Apply manifests with local domain
+sunbeam apply
+
+# Seed secrets
+sunbeam seed
+
+# Verify everything is working
+sunbeam verify
+```
+
+### Production Deployment
+
+```bash
+# Set environment variables
+export SUNBEAM_SSH_HOST=user@your-server.example.com
+
+# Apply production manifests with custom domain
+sunbeam apply --env production --domain sunbeam.pt --email ops@sunbeam.pt
+
+# Check production status
+sunbeam status --env production
+
+# Restart specific service in production
+sunbeam restart ory/kratos --env production
+```
+
+### Debugging a Service Issue
+
+```bash
+# Check service status
+sunbeam status ory/kratos
+
+# View recent logs
+sunbeam logs ory/kratos
+
+# Stream logs in real-time
+sunbeam logs ory/kratos -f
+
+# Get pod details
+sunbeam get ory/kratos-abc123
+
+# Restart the service
+sunbeam restart ory/kratos
+
+# Run health checks
+sunbeam check ory/kratos
+```
+
+## Advanced Usage Patterns
+
+### Partial Manifest Application
+
+```bash
+# Apply only specific namespace
+sunbeam apply lasuite
+
+# Apply multiple namespaces individually
+sunbeam apply ingress
+sunbeam apply ory
+
+# Apply all manifests
+sunbeam apply
+```
+
+### Build and Deploy Workflow
+
+```bash
+# Build an image
+sunbeam build proxy
+
+# Build and push to registry
+sunbeam build proxy --push
+
+# Build, push, and deploy
+sunbeam build proxy --deploy
+
+# Build multiple components
+sunbeam build people-backend --push
+sunbeam build people-frontend --push
+sunbeam build proxy --deploy
+```
+
+### User Management Workflow
+
+```bash
+# Create a new user
+sunbeam user create user@example.com --name "User Name"
+
+# Set user password
+sunbeam user set-password user@example.com "securepassword123"
+
+# List all users
+sunbeam user list
+
+# Get user details
+sunbeam user get user@example.com
+
+# Disable a user (lockout)
+sunbeam user disable user@example.com
+
+# Re-enable a user
+sunbeam user enable user@example.com
+
+# Generate recovery link
+sunbeam user recover user@example.com
+```
+
+## Best Practices
+
+### Environment Management
+
+**Use separate contexts for different environments:**
+
+```bash
+# Local development (default)
+sunbeam status
+
+# Production with explicit context
+sunbeam status --env production --context production
+```
+
+**Set domain appropriately:**
+
+```bash
+# Local development uses automatic Lima IP domain
+sunbeam apply
+
+# Production requires explicit domain
+sunbeam apply --env production --domain sunbeam.pt
+```
+
+### Service Management
+
+**Use targeted restarts:**
+
+```bash
+# Restart specific service instead of all
+sunbeam restart ory/kratos
+
+# Restart namespace instead of entire cluster
+sunbeam restart lasuite
+```
+
+**Monitor service health:**
+
+```bash
+# Check status before and after operations
+sunbeam status ory
+
+# Use health checks for functional verification
+sunbeam check ory/kratos
+```
+
+### Manifest Management
+
+**Apply in logical order:**
+
+```bash
+# Apply infrastructure first
+sunbeam apply ingress
+sunbeam apply data
+
+# Then apply application layers
+sunbeam apply ory
+sunbeam apply lasuite
+```
+
+**Handle webhook dependencies:**
+
+```bash
+# cert-manager must be ready before applying certificates
+# Sunbeam automatically handles this with convergence passes
+sunbeam apply
+```
+
+### Debugging Techniques
+
+**Use kubectl passthrough for advanced debugging:**
+
+```bash
+# Direct kubectl access
+sunbeam k8s get pods -A -o wide
+
+# Describe resources
+sunbeam k8s describe pod ory/kratos-abc123
+
+# View events
+sunbeam k8s get events --sort-by=.metadata.creationTimestamp
+```
+
+**Check VSO secret sync status:**
+
+```bash
+# Status command includes VSO sync information
+sunbeam status
+
+# Look for sync indicators in output
+# ✓ indicates synced, ✗ indicates issues
+```
+
+### Configuration Management
+
+**Use environment variables for sensitive data:**
+
+```bash
+# Set ACME email via environment
+export SUNBEAM_ACME_EMAIL=ops@sunbeam.pt
+sunbeam apply --env production --domain sunbeam.pt
+```
+
+**Manage multiple clusters:**
+
+```bash
+# Use context overrides for different clusters
+sunbeam status --context cluster1
+sunbeam status --context cluster2
+```
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+**Issue: Cluster not starting**
+
+```bash
+# Check Lima VM status
+limactl list
+limactl start sunbeam
+
+# Check cluster components
+sunbeam k8s get nodes
+sunbeam k8s get pods -A
+```
+
+**Issue: Manifest apply failures**
+
+```bash
+# Check for webhook issues
+sunbeam k8s get validatingwebhookconfigurations
+sunbeam k8s get mutatingwebhookconfigurations
+
+# Check cert-manager status
+sunbeam status cert-manager
+sunbeam logs cert-manager/cert-manager
+```
+
+**Issue: Secret sync problems**
+
+```bash
+# Check VSO status
+sunbeam status
+
+# Check OpenBao connection
+sunbeam bao status
+
+# Verify secrets exist
+sunbeam k8s get vaultstaticsecrets -A
+sunbeam k8s get vaultdynamicsecrets -A
+```
+
+**Issue: Service not responding**
+
+```bash
+# Check service status
+sunbeam status ory/kratos
+
+# Check logs
+sunbeam logs ory/kratos -f
+
+# Check service and endpoint
+sunbeam k8s get service ory/kratos
+sunbeam k8s get endpoints ory/kratos
+
+# Restart service
+sunbeam restart ory/kratos
+```
+
+## Integration Patterns
+
+### CI/CD Integration
+
+```yaml
+# Example GitHub Actions workflow
+- name: Deploy to production
+  env:
+    SUNBEAM_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
+  run: |
+    sunbeam apply --env production --domain sunbeam.pt --email ops@sunbeam.pt
+    sunbeam check
+```
+
+### Local Development Workflow
+
+```bash
+# Start fresh each day
+sunbeam down
+sunbeam up
+sunbeam apply
+sunbeam seed
+
+# During development
+sunbeam restart lasuite/people-backend
+sunbeam logs lasuite/people-backend -f
+
+# End of day cleanup
+sunbeam down
+```
+
+### Team Collaboration
+
+```bash
+# Bootstrap new environment
+sunbeam up
+sunbeam apply
+sunbeam seed
+sunbeam bootstrap
+
+# Onboard new team member
+sunbeam user create newuser@company.com --name "New User"
+sunbeam user set-password newuser@company.com "temporary123"
+
+# Share access information
+sunbeam user recover newuser@company.com
+```
+
+## Performance Tips
+
+**Targeted operations:**
+
+```bash
+# Apply only what's needed
+sunbeam apply lasuite  # Instead of sunbeam apply
+
+# Restart only affected services
+sunbeam restart ory/kratos  # Instead of sunbeam restart
+```
+
+**Use namespace filtering:**
+
+```bash
+# Focus on specific areas
+sunbeam status lasuite
+sunbeam logs lasuite/people-backend
+```
+
+**Monitor resource usage:**
+
+```bash
+# Check cluster resource usage
+sunbeam k8s top nodes
+sunbeam k8s top pods -A
+
+# Check specific namespace
+sunbeam k8s top pods -n lasuite
+```
+
+## Security Best Practices
+
+**Secret management:**
+
+```bash
+# Use sunbeam's built-in secret management
+sunbeam seed
+sunbeam verify
+
+# Avoid hardcoding secrets in manifests
+```
+
+**User management:**
+
+```bash
+# Regularly audit users
+sunbeam user list
+
+# Disable unused accounts
+sunbeam user disable olduser@company.com
+
+# Rotate passwords regularly
+sunbeam user set-password user@company.com "newsecurepassword"
+```
+
+**Production access:**
+
+```bash
+# Use SSH host environment variable securely
+export SUNBEAM_SSH_HOST=user@server.example.com
+
+# Never commit SSH host in code
+# Use secret management for production credentials
+```
+
+## Monitoring and Maintenance
+
+**Regular health checks:**
+
+```bash
+# Daily health monitoring
+sunbeam status
+sunbeam check
+
+# Weekly deep checks
+sunbeam verify
+sunbeam k8s get events -A --sort-by=.metadata.creationTimestamp
+```
+
+**Log management:**
+
+```bash
+# Check logs for errors
+sunbeam logs ory/kratos | grep ERROR
+sunbeam logs lasuite/people-backend | grep Exception
+
+# Monitor specific services
+sunbeam logs ingress/nginx-ingress -f
+```
+
+**Resource cleanup:**
+
+```bash
+# Clean up completed jobs
+sunbeam k8s delete jobs --field-selector=status.successful=1
+
+# Remove old resources
+sunbeam k8s delete pods --field-selector=status.phase=Succeeded
+```
+
+## Advanced Patterns
+
+### Custom Domain Management
+
+```bash
+# Discover current domain
+CURRENT_DOMAIN=$(sunbeam k8s get cm gitea-inline-config -n devtools -o jsonpath='{.data.server}' | grep DOMAIN= | cut -d= -f2)
+
+# Apply with custom domain
+sunbeam apply --domain custom.example.com
+```
+
+### Multi-environment Testing
+
+```bash
+# Test changes in local first
+sunbeam apply --env local
+sunbeam check
+
+# Then apply to production
+sunbeam apply --env production --domain sunbeam.pt
+sunbeam check --env production
+```
+
+### Integration with Other Tools
+
+```bash
+# Use with kubectl
+kubectl --context=sunbeam get pods -A
+
+# Use with helm
+helm --kube-context=sunbeam list -A
+
+# Use with k9s (set context first)
+sunbeam k8s config use-context sunbeam
+k9s
+```

docs/utility-modules.md

@@ -0,0 +1,286 @@
+---
+layout: default
+title: Utility Modules
+description: Documentation of Sunbeam's utility and helper modules
+parent: index
+toc: true
+---
+
+# Utility Modules
+
+Sunbeam includes several utility modules that provide essential helper functionality.
+
+## Output Utilities (`sunbeam.output`)
+
+The output module provides consistent formatting for user feedback and status messages.
+
+### Functions
+
+#### `step(msg: str)`
+Print a step header with `==>` prefix.
+
+**Parameters:**
+- `msg`: The message to display
+
+**Example:**
+```python
+step("Starting cluster initialization...")
+# Output: ==> Starting cluster initialization...
+```
+
+#### `ok(msg: str)`
+Print a success or informational message with indentation.
+
+**Parameters:**
+- `msg`: The message to display
+
+**Example:**
+```python
+ok("Cluster initialized successfully")
+# Output:     Cluster initialized successfully
+```
+
+#### `warn(msg: str)`
+Print a warning message to stderr.
+
+**Parameters:**
+- `msg`: The warning message
+
+**Example:**
+```python
+warn("Low memory detected")
+# Output:     WARN: Low memory detected
+```
+
+#### `die(msg: str)`
+Print an error message and exit the program.
+
+**Parameters:**
+- `msg`: The error message
+
+**Example:**
+```python
+die("Failed to connect to cluster")
+# Output: ERROR: Failed to connect to cluster
+# Exits with status code 1
+```
+
+#### `table(rows: list[list[str]], headers: list[str]) -> str`
+Generate an aligned text table.
+
+**Parameters:**
+- `rows`: List of row data (list of strings)
+- `headers`: List of column headers
+
+**Returns:** Formatted table string
+
+**Example:**
+```python
+table_data = table([
+    ["pod-1", "Running", "2/2"],
+    ["pod-2", "Pending", "0/1"]
+], ["Name", "Status", "Ready"])
+
+# Output:
+# Name      Status    Ready
+# -------------------------
+# pod-1     Running   2/2
+# pod-2     Pending   0/1
+```
+
+### Usage Patterns
+
+```python
+from sunbeam.output import step, ok, warn, die, table
+
+# Progress reporting
+step("Deploying application...")
+ok("Namespace created")
+ok("ConfigMaps applied")
+
+# Error handling
+if not cluster_ready:
+    die("Cluster not ready - aborting deployment")
+
+# Warning conditions
+if memory_low:
+    warn("System memory is low - performance may be affected")
+
+# Tabular data display
+pod_data = [
+    ["kratos-abc", "Running", "2/2"],
+    ["hydra-xyz", "Running", "1/1"]
+]
+print(table(pod_data, ["Pod", "Status", "Ready"]))
+```
+
+## Tool Management (`sunbeam.tools`)
+
+The tools module handles automatic downloading, caching, and verification of required binaries.
+
+### Constants
+
+#### `CACHE_DIR`
+Default cache directory: `~/.local/share/sunbeam/bin`
+
+#### `TOOLS`
+Dictionary of supported tools with version and download information:
+
+```python
+TOOLS = {
+    "kubectl": {
+        "version": "v1.32.2",
+        "url": "https://dl.k8s.io/release/v1.32.2/bin/darwin/arm64/kubectl",
+        "sha256": ""
+    },
+    "kustomize": {
+        "version": "v5.8.1",
+        "url": "https://github.com/kubernetes-sigs/kustomize/releases/download/...",
+        "sha256": "",
+        "extract": "kustomize"
+    },
+    "helm": {
+        "version": "v4.1.0",
+        "url": "https://get.helm.sh/helm-v4.1.0-darwin-arm64.tar.gz",
+        "sha256": "82f7065bf4e08d4c8d7881b85c0a080581ef4968a4ae6df4e7b432f8f7a88d0c",
+        "extract": "darwin-arm64/helm"
+    }
+}
+```
+
+### Functions
+
+#### `ensure_tool(name: str) -> Path`
+Ensure a tool is available, downloading and verifying if necessary.
+
+**Parameters:**
+- `name`: Tool name (must be in TOOLS dictionary)
+
+**Returns:** Path to the executable
+
+**Behavior:**
+- Checks cache for existing binary
+- Verifies version and SHA256 hash
+- Downloads if missing or verification fails
+- Extracts from archives if needed
+- Makes executable and sets permissions
+- Caches version information
+
+**Example:**
+```python
+kubectl_path = ensure_tool("kubectl")
+subprocess.run([str(kubectl_path), "version"])
+```
+
+#### `run_tool(name: str, *args, **kwargs) -> subprocess.CompletedProcess`
+Run a tool, ensuring it's downloaded first.
+
+**Parameters:**
+- `name`: Tool name
+- `*args`: Arguments to pass to the tool
+- `**kwargs`: Additional subprocess.run parameters
+
+**Returns:** CompletedProcess result
+
+**Special Handling:**
+- For kustomize: Adds CACHE_DIR to PATH so helm is found
+- Automatically ensures tool is available before running
+
+**Example:**
+```python
+result = run_tool("kustomize", "build", "overlays/local", 
+                  capture_output=True, text=True)
+print(result.stdout)
+```
+
+#### `_sha256(path: Path) -> str`
+Calculate SHA256 hash of a file (internal utility).
+
+**Parameters:**
+- `path`: Path to file
+
+**Returns:** Hexadecimal SHA256 hash
+
+### Tool Management Workflow
+
+```mermaid
+flowchart TD
+    A[ensure_tool] --> B{Tool in cache?}
+    B -->|Yes| C{Version matches?}
+    C -->|Yes| D{SHA256 matches?}
+    D -->|Yes| E[Return cached path]
+    B -->|No| F[Download]
+    C -->|No| F
+    D -->|No| F
+    F --> G{Extract needed?}
+    G -->|Yes| H[Extract from archive]
+    G -->|No| I[Save binary]
+    H --> I
+    I --> J{Verify SHA256?}
+    J -->|Yes| K{Hash matches?}
+    K -->|Yes| L[Set executable]
+    K -->|No| M[Error: Hash mismatch]
+    J -->|No| L
+    L --> N[Write version file]
+    N --> E
+```
+
+### Error Handling
+
+The module includes comprehensive error handling:
+
+- **Unknown tools**: Raises `ValueError` for unsupported tools
+- **Download failures**: Propagates network errors
+- **SHA256 mismatches**: Raises `RuntimeError` with expected vs actual hashes
+- **Permission issues**: Handles file system errors gracefully
+
+## Helper Functions
+
+### Target Parsing (`sunbeam.kube.parse_target`)
+
+```python
+def parse_target(s: str | None) -> tuple[str | None, str | None]:
+    """Parse 'ns/name' -> ('ns', 'name'), 'ns' -> ('ns', None), None -> (None, None)."""
+```
+
+**Examples:**
+```python
+parse_target("ory/kratos")    # ("ory", "kratos")
+parse_target("lasuite")       # ("lasuite", None)
+parse_target(None)             # (None, None)
+```
+
+### Domain Replacement (`sunbeam.kube.domain_replace`)
+
+```python
+def domain_replace(text: str, domain: str) -> str:
+    """Replace all occurrences of DOMAIN_SUFFIX with domain."""
+```
+
+**Example:**
+```python
+manifest = "apiVersion: v1\nkind: Service\nspec:\n  host: app.DOMAIN_SUFFIX"
+domain_replace(manifest, "example.com")
+# Returns: "apiVersion: v1\nkind: Service\nspec:\n  host: app.example.com"
+```
+
+### Lima VM IP Discovery (`sunbeam.kube.get_lima_ip`)
+
+```python
+def get_lima_ip() -> str:
+    """Get the socket_vmnet IP of the Lima sunbeam VM (192.168.105.x)."""
+```
+
+Uses multiple fallback methods to discover the Lima VM IP address.
+
+### Domain Discovery (`sunbeam.kube.get_domain`)
+
+```python
+def get_domain() -> str:
+    """Discover the active domain from cluster state."""
+```
+
+Discovery priority:
+1. Gitea inline-config secret
+2. La Suite OIDC provider configmap
+3. Lima VM IP with sslip.io domain