@sembix/cli 1.4.1 → 1.5.1

package/README.md

@@ -1,310 +1,210 @@
 # Sembix CLI
 
-A terminal-based CLI tool for managing Sembix products. An intuitive command-line interface designed for technical users.
+A unified CLI for managing Sembix Studio with two main capabilities:
+1. **Environment Management** (`sembix studio`) - Create and manage GitHub Actions environments for AWS deployments
+2. **Environment Interaction** (`sembix workflow`, `sembix project`) - Execute and manage workflows on running Studio instances
 
 ## Table of Contents
 
-- [Features](#features)
 - [Prerequisites](#prerequisites)
-- [Deployment Process](#deployment-process)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-  - [GitHub Deployment Quick Start](#github-deployment-quick-start)
-  - [Studio CLI Quick Start](#studio-cli-quick-start)
-- [Configuration](#configuration)
-  - [Option 1: Interactive Configuration (Recommended)](#option-1-interactive-configuration-recommended)
-  - [Option 2: Environment Variables (.env file)](#option-2-environment-variables-env-file)
-  - [Option 3: Config File (Recommended for Automation)](#option-3-config-file-recommended-for-automation)
-  - [Creating a GitHub Token](#creating-a-github-token)
-  - [Credential Priority](#credential-priority)
-- [Commands](#commands)
-  - [Global Commands](#global-commands)
-  - [Studio Deployment Commands](#studio-deployment-commands)
-  - [Studio API Commands](#studio-api-commands)
-  - [Global Options](#global-options)
-- [Usage Examples](#usage-examples)
-  - [Basic Usage Patterns](#basic-usage-patterns)
+- **[Part 1: Environment Management](#part-1-environment-management)**
+  - [Concepts](#concepts)
+  - [Command Reference](#command-reference)
+    - [studio create](#sembix-studio-create-name)
+    - [studio update](#sembix-studio-update-name)
+    - [studio add-hub](#sembix-studio-add-hub-name)
+    - [studio list](#sembix-studio-list-repository)
+  - [Configuration](#configuration)
   - [Common Workflows](#common-workflows)
-  - [Profile Management](#profile-management-examples)
-  - [Error Handling](#error-handling-examples)
-  - [Best Practices](#best-practices)
-- [Studio CLI](#studio-cli)
-  - [Studio Configuration](#studio-configuration)
+- **[Part 2: Environment Interaction](#part-2-environment-interaction)**
+  - [Concepts](#concepts-1)
   - [Authentication](#authentication)
-  - [Workflow Operations](#workflow-operations)
-- [Workflow](#workflow)
-- [Configuration Priority](#configuration-priority)
-- [Config File Reference](#config-file-reference)
-- [Use Cases](#use-cases)
+  - [Command Reference](#command-reference-1)
+    - [Profile Management](#profile-management)
+    - [Project Management](#project-management)
+    - [Workflow Operations](#workflow-operations)
+  - [Common Workflows](#common-workflows-1)
+- [Global Configuration](#global-configuration)
+  - [sembix configure](#sembix-configure)
+  - [Environment Variables](#environment-variables)
+  - [Global Options](#global-options)
 - [Troubleshooting](#troubleshooting)
-  - [Authentication Issues](#authentication-issues)
-  - [GitHub API Issues](#github-api-issues)
-  - [Studio API Issues](#studio-api-issues)
-  - [Common Errors](#common-errors)
 - [Development](#development)
-- [Advanced Topics](#advanced-topics)
-- [License](#license)
-- [Support](#support)
-- [See Also](#see-also)
-
-## Features
-
-- 🚀 **Interactive Setup** - Guided prompts for environment configuration with detailed explanations
-- 📝 **Config File Support** - YAML configuration files for version-controlled, repeatable setups
-- 🎯 **50+ CLI Flags** - Complete automation support with flags for every configuration option
-- 🔐 **GitHub Integration** - Direct GitHub API integration for environment and secrets management
-- ✅ **Validation** - Real-time input validation for AWS resources, IAM roles, and more
-- 🔄 **Update Command** - Modify existing environments without recreation
-- 🔗 **Hub Integration** - Built-in Hub configuration as part of the main workflow
-- 🎨 **Beautiful UI** - Clean, colorful terminal interface with spinners and status updates
-- ⚡ **Priority Chain** - CLI flags > Config file > Interactive prompts > Defaults
-- 🌐 **Studio Integration** - Connect to Sembix Studio instances with profile-based configuration
-- 🔐 **Cognito Authentication** - Browser-based OAuth flow with automatic token refresh
-- 🔄 **Workflow Execution** - Start, monitor, and manage workflow runs remotely
-- 👤 **Profile Management** - Manage multiple Studio instances like AWS CLI profiles
-- 📊 **Output Formatting** - JSON, pretty-print, or text output for all commands
-- 🎯 **Project Management** - List, search, and view project details
-- 🔗 **Profile Defaults** - Set default projects per profile for faster workflow execution
+- [Complete Studio Options](#complete-studio-options)
 
 ## Prerequisites
 
-- **Node.js** 20 or higher
-- **GitHub Personal Access Token** with the following scopes:
-  - `repo` - Full control of private repositories
-  - `workflow` - Update GitHub Action workflows
-- **Deployment Repository** - A GitHub repository set up for Sembix Studio deployments
-
-### For Studio Integration (Optional)
-- **Sembix Studio Instance** - Access to a Sembix Studio deployment
-- **Cognito Configuration** - User Pool ID, Client ID, and Domain from Studio admin
-
-## Deployment Process
-
-Sembix Studio uses a **two-phased deployment** process to establish secure cross-account access with the Sembix Hub:
-
-### Phase 1: Bootstrap & Initial Deployment
-
-1. **Create environment** - Run `sembix studio create` to configure your environment (Steps 1-8)
-   - Skip Hub integration initially (use `--skip-hub` or skip Step 9)
-   - Creates GitHub Actions environment with AWS configuration
-
-2. **Bootstrap deployment** - Run the GitHub Actions workflow
-   - Deploys initial Terraform infrastructure
-   - Creates IAM roles and resources in your AWS account
-   - Produces IAM ARNs needed for Hub integration
-
-3. **Coordinate with Sembix Support** - Send the IAM ARNs to Sembix support
-   - Sembix configures the Hub to trust your account
-   - Sembix provides Hub role ARNs back to you:
-     - Hub Engine Execution Role ARN
-     - Hub Consumer Role ARN
-     - Hub Admin Role ARN
-     - Hub AppConfig Role ARN (plus Application ID, Environment ID, Profile ID)
-
-### Phase 2: Hub Integration & Full Deployment
-
-4. **Add Hub integration** - Run `sembix studio add-hub` with ARNs from Sembix support
-   - Updates GitHub Actions environment with Hub role ARNs
-   - Configures cross-account access to Sembix Hub
-
-5. **Final deployment** - Run the GitHub Actions workflow again
-   - Completes full Sembix Studio deployment
-   - Enables Hub cross-account access
-   - Your Studio environment is now fully operational
-
-**Important:** Do not skip Phase 1. The Hub integration requires IAM resources created during the bootstrap deployment.
+- Node.js 20 or higher
+- For environment management: GitHub Personal Access Token with `repo` and `workflow` scopes
+- For environment interaction: Access to a Sembix Studio instance with Cognito credentials
 
 ## Installation
 
-### From npm (Recommended)
-
 ```bash
+# From npm
 npm install -g @sembix/cli
-```
-
-### From Source
 
-```bash
-npm install
-npm run build
-
-# Link globally for development
+# From source
+git clone <repo>
+npm install && npm run build
 npm link
 ```
 
-### Development Mode
-
-```bash
-npm install
-npm run dev -- studio create
-```
-
 ## Quick Start
 
-Get started with the Sembix CLI in 5 minutes. Choose the workflow that matches your needs:
-
-### GitHub Deployment Quick Start
-
-**Step 1: Configure credentials**
+### Initial Configuration
 
 ```bash
 sembix configure
 ```
 
 Prompts for:
-- GitHub Personal Access Token (required)
-- Default GitHub organization (optional)
-
-**Step 2: Create environment**
-
-```bash
-# Interactive mode (recommended for first-time)
-sembix studio create
-
-# Or with repository specified
-sembix studio create --repo owner/repo
-```
-
-This interactive wizard walks you through 9 configuration steps and creates your GitHub Actions environment with all required secrets.
-
-**Step 3: Deploy via GitHub Actions**
+- GitHub token (for environment management)
+- Optionally: Studio profile (for environment interaction)
 
-1. Go to your repository's Actions tab
-2. Select the deployment workflow
-3. Choose your environment
-4. Run the workflow
-5. Copy the Hub role ARNs from deployment output
-
-**Step 4: Add Hub integration**
+### Environment Management (GitHub Deployment)
 
 ```bash
-sembix studio add-hub production
+# Create GitHub Actions environment
+sembix studio create production --repo owner/repo
 
-# Or with repository specified
+# After first deployment, add Hub integration
 sembix studio add-hub production --repo owner/repo
-```
 
-Enter the Hub role ARNs from the deployment output.
+# List environments
+sembix studio list owner/repo
+```
 
-**Step 5: Deploy again**
+### Environment Interaction (Studio API)
 
-Run the GitHub Actions workflow again with Hub enabled. Your Studio environment is now fully operational!
+```bash
+# Authenticate with Studio instance
+sembix login
 
-### Studio CLI Quick Start
+# Start a workflow
+sembix workflow start
 
-**Step 1: Configure Studio profile**
+# Monitor workflow status
+sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
 
-```bash
-sembix configure
+# List projects
+sembix project list
 ```
 
-After GitHub credentials, choose to configure a Studio profile with:
-- Profile name (e.g., "production")
-- Studio API URL
-- Cognito User Pool ID, Client ID, Domain, and Region
+---
 
-**Step 2: Authenticate**
+# Part 1: Environment Management
 
-```bash
-# Login with default profile
-sembix login
+## Concepts
 
-# Or specific profile
-sembix login --profile production
-```
+The `sembix studio` commands automate GitHub Actions environment creation for Sembix Studio AWS deployments. They create GitHub environments with encrypted secrets and variables required for Terraform-based infrastructure deployment.
 
-Opens your browser for Cognito authentication. Tokens are stored securely and refreshed automatically.
+**Deployment Process:**
+1. **Bootstrap** - Create environment → Run GitHub Actions → Get IAM ARNs
+2. **Hub Integration** - Add Hub ARNs → Run GitHub Actions again → Full deployment
 
-**Step 3: Start a workflow**
+## Command Reference
 
-```bash
-# Interactive mode (recommended)
-sembix workflow start
+### `sembix studio create [name]`
 
-# With explicit IDs
-sembix workflow start --project-id proj_123 --workflow-id wf_456
+Create a new GitHub Actions environment for Studio deployment.
 
-# With workflow name
-sembix workflow start --project-id proj_123 --workflow-name "Deploy"
-```
+```bash
+# Interactive mode (guided prompts)
+sembix studio create
 
-**Step 4: Monitor workflow**
+# With repository and name
+sembix studio create production --repo owner/repo
 
-```bash
-# Check status
-sembix workflow run status --workflow-id wf_456 --run-id run_789
+# With YAML config file
+sembix studio create --config production.yaml
 
-# Watch until completion
-sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
+# Skip Hub integration (add later)
+sembix studio create production --repo owner/repo --skip-hub
 ```
 
-### Common Tasks Cheat Sheet
-
-```bash
-# List environments
-sembix studio list owner/repo
+**Key Options:**
+- `-r, --repo <repo>` - Target repository (owner/repo)
+- `-c, --config <path>` - YAML configuration file
+- `-t, --token <token>` - GitHub token (overrides config)
+- `-e, --env <name>` - Environment name
+- `--skip-hub` - Skip Hub integration step
 
-# List profiles
-sembix profile list
+**Configuration Categories:**
+- AWS: `--aws-account-id`, `--aws-region`, `--customer-role-arn`, `--terraform-state-bucket`
+- Database: `--database-name`, `--database-user`
+- Networking: `--vpc-cidr`, `--custom-vpc-id`, `--subnet-ids`, `--enable-vpc-endpoints`
+- Security: `--sg-*` (security groups), `--iam-*` (IAM roles), `--use-custom-*`
+- TLS/DNS: `--cloudfront-domain`, `--cloudfront-cert-arn`, `--bff-alb-cert-arn`, `--hosted-zone-id`
+- Features: `--deploy-studio-memory`, `--deploy-studio-notifications`, `--enable-bff-waf`
+- Frontend: `--github-app-client-id`, `--jira-client-id`
+- Hub: `--hub-engine-execution-role`, `--hub-consumer-role`, `--hub-admin-role`
 
-# Set default project
-sembix profile set-default-project production proj_123
+[See all 50+ options](#complete-studio-options)
 
-# List projects
-sembix project list
+### `sembix studio update [name]`
 
-# List workflows
-sembix workflow list
+Update an existing GitHub Actions environment. Only provide flags you want to change.
 
-# List workflow runs
-sembix workflow run list --workflow-id wf_456
+```bash
+# Add Hub integration
+sembix studio update production --repo owner/repo \
+  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine \
+  --hub-consumer-role arn:aws:iam::123456789012:role/HubConsumer
 
-# Stop a workflow
-sembix workflow run stop --workflow-id wf_456 --run-id run_789
+# Update feature flags
+sembix studio update production --repo owner/repo \
+  --deploy-studio-memory true
 ```
 
-For detailed documentation, see the sections below.
+### `sembix studio add-hub [name]`
 
-## Configuration
-
-### Option 1: Interactive Configuration (Recommended)
-
-The easiest way to get started is using the interactive configuration command:
+Add Sembix Hub integration to an existing environment (Phase 2 of deployment).
 
 ```bash
-sembix configure
+sembix studio add-hub production --repo owner/repo
 ```
 
-This will prompt you for:
-- **GitHub Personal Access Token** (required)
-- **Default GitHub Organization** (optional)
-
-Your credentials will be securely stored in `~/.sembix/config` with restricted file permissions (0600).
+Interactive prompts for Hub role ARNs (or use flags):
+- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN
+- `--hub-consumer-role <arn>` - Hub Consumer Role ARN
+- `--hub-admin-role <arn>` - Hub Admin Role ARN
+- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN (optional)
 
-### Option 2: Environment Variables (.env file)
+### `sembix studio list [repository]`
 
-Alternatively, create a `.env` file in the project root directory:
+List GitHub Actions environments.
 
 ```bash
-cp .env.example .env
+sembix studio list                    # All accessible repositories
+sembix studio list owner/repo         # Specific repository
 ```
 
-Edit `.env` and add your GitHub token:
+## Configuration
 
-```env
-# GitHub Personal Access Token
-GITHUB_TOKEN=ghp_your_token_here
+### Priority Chain
 
-# Optional: Default GitHub organization
-DEFAULT_GITHUB_ORG=your-org
-```
+Configuration values are resolved in this order (highest to lowest):
+1. **CLI Flags** - Explicit command-line options
+2. **Config File** - YAML file (via `--config`)
+3. **Interactive Prompts** - User input during execution
+4. **Defaults** - Built-in defaults
+
+### GitHub Token Priority
+
+GitHub token is resolved in this order:
+1. `--token` flag
+2. `GITHUB_TOKEN` environment variable
+3. `~/.sembix/config` (via `sembix configure`)
+4. `.env` file
 
-### Option 3: Config File (Recommended for Automation)
+### YAML Config File
 
-Create a YAML config file for your environment:
+Create `production.yaml`:
 
 ```yaml
-# production.yaml
 repository:
   owner: acme-corp
   repo: sembix-deployment
@@ -319,330 +219,118 @@ database:
   name: sembix_studio
   user: sembix_studio_user
 
-# ... see config.example.yaml for complete structure
-```
-
-See [`config.example.yaml`](./config.example.yaml) for a complete configuration example.
-
-### Creating a GitHub Token
-
-1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
-2. Click "Generate new token (classic)"
-3. Select scopes:
-   - ✅ `repo` (all sub-scopes)
-   - ✅ `workflow`
-4. Generate and copy the token
-5. Run `sembix configure` to store it securely, or add to `.env` file, or use `--token` flag
-
-### Credential Priority
-
-The CLI checks for credentials in this order (highest to lowest priority):
-1. `--token` flag
-2. `GITHUB_TOKEN` environment variable
-3. `~/.sembix/config` (created by `sembix configure`)
-4. Project `.env` file
-
-## Commands
-
-Complete reference for all Sembix CLI commands.
-
-### Command Structure
-
-```
-sembix <product> <action> [options] [arguments]
-```
-
-- **product**: The Sembix product (e.g., `studio`)
-- **action**: What you want to do (e.g., `create`, `list`, `add-hub`)
-- **options**: Flags like `--token` or `--repo`
-- **arguments**: Required or optional values (e.g., environment name)
-
----
-
-### Global Commands
-
-#### `sembix configure`
-
-Configure Sembix CLI credentials and settings interactively.
-
-**Usage:**
-
-```bash
-sembix configure
-```
-
-**What it does:**
-
-1. Prompts for your GitHub Personal Access Token
-2. Prompts for your default GitHub organization (optional)
-3. Optionally prompts to configure a Sembix Studio profile for API access:
-   - Studio API URL
-   - Cognito User Pool ID, Client ID, Region, and Domain
-4. Saves configuration to `~/.sembix/config` with secure permissions (0600)
-
-**When to use:**
-
-- First time setup (recommended)
-- Updating your GitHub token
-- Changing your default organization
-- Adding or updating Studio profiles for API access
-
-**Example:**
-
-```bash
-$ sembix configure
-
-  Configure Sembix CLI
-
-This will store your configuration in:
-  ~/.sembix/config
-
-? GitHub Personal Access Token: ****
-? Default GitHub Organization (optional): acme-corp
-? Configure Sembix Studio profile? Yes
-
-━━━ Studio Profile Configuration ━━━
-
-? Profile name: production
-? Studio API URL: https://studio.example.com
-? Cognito User Pool ID: us-east-1_ABC123
-? Cognito Client ID: 1a2b3c4d5e6f7g8h9i0j
-? Cognito Region: us-east-1
-? Cognito Domain: https://auth.example.com
-
-✓ Configuration saved successfully!
-✓ Studio profile 'production' configured successfully!
-```
-
----
-
-### Studio Deployment Commands
-
-Commands for managing Sembix Studio GitHub Actions deployments.
-
-#### `sembix studio create [name]`
-
-Create a new Sembix Studio environment with full interactive configuration.
-
-**Usage:**
-
-```bash
-# Interactive mode
-sembix studio create
-
-# With environment name
-sembix studio create production
-
-# With name and repository
-sembix studio create production --repo acme/deploy
-```
-
-**Key Options:**
-
-```bash
--r, --repo <repo>              Target repository (owner/repo)
--e, --env <environment>        Environment name
--t, --token <token>            GitHub personal access token
--c, --config <path>            Path to YAML configuration file
-
-# AWS Configuration
---aws-account-id <id>          AWS Account ID (12 digits)
---aws-region <region>          AWS Region
---customer-role-arn <arn>      GitHub Actions IAM role ARN
---terraform-state-bucket <bucket>  Terraform state S3 bucket
-
-# Database
---database-name <name>         PostgreSQL database name
---database-user <user>         PostgreSQL database user
-
-# Networking
---enable-vpc-endpoints <boolean>     Enable VPC endpoints (true/false)
---use-custom-networking <boolean>    Use existing VPC (true/false)
---vpc-cidr <cidr>                    VPC CIDR block (e.g., 10.0.0.0/16)
---public-subnet-cidrs <json>         Public subnet CIDRs (JSON array)
---private-subnet-cidrs <json>        Private subnet CIDRs (JSON array)
---az-count <count>                   Number of AZs (2 or 3)
---custom-vpc-id <id>                 Existing VPC ID
---custom-public-subnet-ids <ids>     Existing public subnet IDs (comma-separated)
---custom-private-subnet-ids <ids>    Existing private subnet IDs (comma-separated)
-
-# Security - Security Groups
---use-custom-security-groups <boolean>  Use custom security groups (true/false)
---sg-workflow-engine <id>            Workflow Engine security group ID
---sg-aurora <id>                     Aurora database security group ID
---sg-rds-proxy <id>                  RDS Proxy security group ID
---sg-bff-ecs <id>                    BFF ECS service security group ID
---sg-bastion <id>                    Bastion host security group ID
---sg-bff-alb <id>                    BFF ALB security group ID
---sg-semantic-event-engine <id>      Semantic Event Engine security group ID
-
-# Security - IAM Roles
---use-custom-iam-roles <boolean>     Use custom IAM roles (true/false)
---iam-workflow-engine-exec <arn>     Workflow Engine execution role ARN
---iam-workflow-engine-task <arn>     Workflow Engine task role ARN
---iam-bff-ecs-exec <arn>             BFF ECS task execution role ARN
---iam-bff-ecs-task <arn>             BFF ECS task role ARN
---iam-semantic-event-engine-exec <arn>   Semantic Event Engine execution role ARN
---iam-semantic-event-engine-task <arn>   Semantic Event Engine task role ARN
---iam-rds-proxy <arn>                RDS Proxy role ARN
---iam-studio-memory <arn>            Studio Memory role ARN
---iam-studio-notification <arn>      Studio Notification role ARN
-
-# TLS/DNS
---cloudfront-domain <domain>   CloudFront custom domain
---cloudfront-cert-arn <arn>    CloudFront SSL certificate ARN (us-east-1)
---bff-alb-cert-arn <arn>       BFF ALB SSL certificate ARN
---hosted-zone-id <id>          Route53 hosted zone ID
-
-# Hub Integration
---skip-hub                     Skip Hub integration
---hub-engine-execution-role <arn>  Hub Engine Execution Role ARN
---hub-consumer-role <arn>      Hub Consumer Role ARN
---hub-admin-role <arn>         Hub Admin Role ARN
-```
+networking:
+  enableVpcEndpoints: true
+  useCustomNetworking: false
+  vpcCidr: 10.0.0.0/16
+  azCount: 2
 
-**Examples:**
+tls:
+  cloudfrontDomain: studio.acme.com
+  cloudfrontCertArn: arn:aws:acm:us-east-1:123456789012:certificate/abc123
+  bffAlbCertificateArn: arn:aws:acm:us-east-1:123456789012:certificate/def456
+  hostedZoneId: Z1234567890ABC
 
-```bash
-# Fully interactive
-sembix studio create
+frontend:
+  githubAppClientId: Iv1.0123456789abcdef
+  githubAppName: sembix-studio-app
+  jiraClientId: abc123def456
 
-# With config file
-sembix studio create --config production.yaml
+features:
+  deployStudioMemory: true
+  deployStudioNotifications: false
+  enableBffWaf: false
 
-# Skip Hub (add later)
-sembix studio create production --repo acme/deploy --skip-hub
+# Hub integration (optional, add after Phase 1)
+hub:
+  engineExecutionRoleArn: arn:aws:iam::999888777666:role/HubEngine
+  consumerRoleArn: arn:aws:iam::999888777666:role/HubConsumer
+  adminRoleArn: arn:aws:iam::999888777666:role/HubAdmin
 ```
 
-**What it does:**
-
-1. Validates repository and environment name
-2. Walks through 9 configuration steps
-3. Creates GitHub Actions environment
-4. Sets environment variables and encrypted secrets
+See [`config.example.yaml`](./config.example.yaml) for complete reference with all options.
 
-See [complete options list](#sembix-studio-create-all-options) below for all 50+ flags.
-
-#### `sembix studio update [name]`
-
-Update an existing Sembix Studio environment.
-
-**Usage:**
+## Common Workflows
 
+**First-time setup:**
 ```bash
-sembix studio update production --repo acme/deploy
+sembix studio create --config base.yaml --skip-hub
+# → Run GitHub Actions → Get IAM ARNs → Send to Sembix
+sembix studio add-hub production --repo owner/repo
+# → Run GitHub Actions again → Full deployment
 ```
 
-**Options:** Same as `create` command
-
-**Examples:**
-
+**Update existing environment:**
 ```bash
-# Add Hub integration
-sembix studio update production --repo acme/deploy \
-  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine
-
-# Update feature flags
-sembix studio update production --repo acme/deploy \
+sembix studio update production --repo owner/repo \
   --deploy-studio-memory true
 ```
 
-#### `sembix studio add-hub [name]`
-
-Add Sembix Hub integration to an existing environment (Phase 2 deployment).
-
-**Usage:**
-
-```bash
-sembix studio add-hub production --repo acme/deploy
-```
-
-**Options:**
-
-- `-r, --repo <repo>` - Target repository
-- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN
-- `--hub-consumer-role <arn>` - Hub Consumer Role ARN
-- `--hub-admin-role <arn>` - Hub Admin Role ARN
-- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN (optional)
-- `--hub-appconfig-app-id <id>` - Hub AppConfig Application ID (optional)
-- `--hub-appconfig-env-id <id>` - Hub AppConfig Environment ID (optional)
-- `--hub-appconfig-profile-id <id>` - Hub AppConfig Profile ID (optional)
-
-**Example:**
-
-```bash
-sembix studio add-hub production \
-  --repo acme/deploy \
-  --hub-engine-execution-role arn:aws:iam::999888777666:role/HubEngineRole \
-  --hub-consumer-role arn:aws:iam::999888777666:role/HubConsumerRole \
-  --hub-admin-role arn:aws:iam::999888777666:role/HubAdminRole
-```
-
-#### `sembix studio list [repository]`
-
-List GitHub Actions environments in a repository.
-
-**Usage:**
-
+**Create multiple environments:**
 ```bash
-# List all your repositories
-sembix studio list
-
-# List environments in specific repository
-sembix studio list acme-corp/sembix-deployment
+sembix studio create prod --repo owner/repo --config prod.yaml
+sembix studio create staging --repo owner/repo --config staging.yaml
 ```
 
 ---
 
-### Studio API Commands
+# Part 2: Environment Interaction
+
+## Concepts
 
-Commands for authenticating with and managing Sembix Studio via API.
+The Sembix CLI provides commands to interact with running Sembix Studio instances. Use these commands to execute workflows, manage projects, and monitor workflow runs.
 
-#### `sembix login [profile]`
+**Two Authentication Methods:**
+1. **Browser OAuth** - For local development (interactive login)
+2. **Client Credentials** - For CI/CD (M2M authentication)
 
-Authenticate with Sembix Studio via Cognito OAuth.
+## Authentication
 
-**Usage:**
+### Local Development (Browser OAuth)
 
 ```bash
-# Login with default profile
+# Login (opens browser)
 sembix login
 
-# Login with specific profile
-sembix login production
-# or
+# Login to specific profile
 sembix login --profile production
-```
 
-**What it does:**
-
-1. Opens browser for Cognito authentication
-2. Exchanges OAuth code for access tokens
-3. Stores tokens securely in `~/.sembix/tokens/<profile>.json`
-4. Tokens are automatically refreshed when expired
+# Logout
+sembix logout --profile production
 
-#### `sembix logout [profile]`
+# Logout from all profiles
+sembix logout --all
+```
 
-Log out from Sembix Studio by removing stored tokens.
+Tokens are stored in `~/.sembix/tokens/<profile>.json` and automatically refreshed.
 
-**Usage:**
+### CI/CD (Client Credentials)
 
+Set environment variables:
 ```bash
-# Logout from default profile
-sembix logout
+export SEMBIX_CLIENT_ID="7a8b9c0d1e2f3g4h"
+export SEMBIX_CLIENT_SECRET="your-secret"
+```
 
-# Logout from specific profile
-sembix logout production
+No login required - CLI automatically uses client credentials when detected.
 
-# Logout from all profiles
-sembix logout --all
+**GitHub Actions Example:**
+```yaml
+- name: Start workflow
+  env:
+    SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
+    SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
+  run: |
+    sembix workflow start --project-id proj_123 --workflow-id wf_456
 ```
 
-#### Profile Commands
+## Command Reference
+
+### Profile Management
 
 **`sembix profile list`**
 
-List all configured Studio profiles with authentication status.
+List all configured Studio profiles.
 
 ```bash
 sembix profile list
@@ -650,7 +338,7 @@ sembix profile list
 
 **`sembix profile show <name>`**
 
-Show detailed information for a specific profile.
+Show profile details.
 
 ```bash
 sembix profile show production
@@ -658,7 +346,7 @@ sembix profile show production
 
 **`sembix profile set-default <name>`**
 
-Set a profile as the default.
+Set default profile.
 
 ```bash
 sembix profile set-default production
@@ -666,7 +354,7 @@ sembix profile set-default production
 
 **`sembix profile delete <name>`**
 
-Delete a profile and its stored tokens.
+Delete a profile and its tokens.
 
 ```bash
 sembix profile delete staging
@@ -674,33 +362,17 @@ sembix profile delete staging
 
 **`sembix profile set-default-project <profile> <project-id>`**
 
-Set a default project for a profile (allows omitting `--project-id` in commands).
+Set default project for a profile (allows omitting `--project-id` in commands).
 
 ```bash
 sembix profile set-default-project production proj_abc123
 ```
 
-**`sembix profile get-default-project <profile>`**
-
-Get the default project for a profile.
-
-```bash
-sembix profile get-default-project production
-```
-
-**`sembix profile clear-default-project <profile>`**
-
-Clear the default project for a profile.
-
-```bash
-sembix profile clear-default-project production
-```
-
-#### Project Commands
+### Project Management
 
 **`sembix project list`**
 
-List and search projects in your Studio instance.
+List projects in Studio instance.
 
 ```bash
 # List all projects
@@ -718,13 +390,33 @@ sembix project list --pretty
 
 **`sembix project show`**
 
-Show details for a specific project.
+Show project details.
 
 ```bash
 sembix project show --project-id proj_abc123
 ```
 
-#### Workflow Commands
+### Workflow Operations
+
+**`sembix workflow list`**
+
+List workflow instances (definitions).
+
+```bash
+# List all workflows
+sembix workflow list
+
+# Filter by project
+sembix workflow list --project-id proj_123
+```
+
+**`sembix workflow template show`**
+
+Show workflow template with input variable details (useful for discovering input names).
+
+```bash
+sembix workflow template show --project-id proj_123 --workflow-id wf_456
+```
 
 **`sembix workflow start`**
 
@@ -734,13 +426,13 @@ Start a workflow instance (creates a new run).
 # Interactive mode (prompts for project, workflow, inputs)
 sembix workflow start
 
-# With project ID and workflow ID
+# With project and workflow IDs
 sembix workflow start --project-id proj_123 --workflow-id wf_456
 
-# With workflow name
+# With workflow name instead of ID
 sembix workflow start --project-id proj_123 --workflow-name "Deploy"
 
-# With inline JSON inputs
+# With inline JSON inputs (using input variable names)
 sembix workflow start --project-id proj_123 --workflow-id wf_456 \
   --inputs '{"environment":"production","version":"1.2.3"}'
 
@@ -749,31 +441,115 @@ sembix workflow start --project-id proj_123 --workflow-id wf_456 \
   --inputs @inputs.json
 
 # Using default project (set via profile set-default-project)
-sembix workflow start --workflow-id wf_456 --inputs '{...}'
+sembix workflow start --workflow-id wf_456 --inputs '{"key":"value"}'
+
+# Non-interactive mode
+sembix workflow start --project-id proj_123 --workflow-id wf_456 --no-interactive
 ```
 
 **Options:**
-
 - `-p, --profile <name>` - Profile to use
 - `--project-id <id>` - Project ID (uses default if not specified)
-- `--workflow-id <id>` - Workflow ID (OR use --workflow-name)
-- `--workflow-name <name>` - Workflow name (OR use --workflow-id)
-- `--inputs <json>` - Input variables as JSON string or @file.json
+- `--workflow-id <id>` - Workflow ID (or use `--workflow-name`)
+- `--workflow-name <name>` - Workflow name (or use `--workflow-id`)
+- `--inputs <json>` - Input variables as JSON or @file.json
 - `--workspace-id <id>` - Workspace ID (optional)
 - `--issue-id <id>` - Issue ID (optional)
 - `--no-interactive` - Disable interactive prompts
 
-**`sembix workflow list`**
+**Input Formats:**
 
-List workflow instances (definitions).
+The `--inputs` flag supports three formats:
 
-```bash
-# List all workflows
-sembix workflow list
+1. **Name-based format (recommended):**
+   ```bash
+   --inputs '{"repositoryUrl": "https://github.com/acme/repo", "branch": "main"}'
+   ```
+   - Uses input variable names from the workflow template
+   - CLI automatically resolves names to IDs and validates inputs
+   - Required fields must be provided with non-empty values
+   - Optional fields can be omitted (will be filled with empty strings)
 
-# Filter by project
-sembix workflow list --project-id proj_123
-```
+2. **ID-based format:**
+   ```bash
+   --inputs '[{"id": "var_123", "instruction": "value"}, {"id": "var_456", "instruction": "main"}]'
+   ```
+   - Uses input variable IDs directly
+   - Useful when you know the exact IDs
+   - Still validates required fields and data types
+
+3. **File-based format:**
+   ```bash
+   --inputs @inputs.json
+   ```
+   - Reads inputs from a JSON file
+   - File can contain name-based or ID-based format
+
+**Input Validation:**
+
+The CLI validates all inputs before starting the workflow:
+
+- **Required fields**: Must have non-empty values
+  ```bash
+  # Error: Missing required field
+  --inputs '{"branch": "main"}'
+  # Error: Required input "repositoryUrl" is missing or empty
+  ```
+
+- **Boolean fields**: Must be `true` or `false` (converted to strings)
+  ```bash
+  # Valid
+  --inputs '{"enabled": true, "dryRun": false}'
+  --inputs '{"enabled": "true", "dryRun": "false"}'
+  ```
+
+- **Optional fields**: Automatically filled with empty strings if not provided
+  ```bash
+  # Input: Only required fields provided
+  --inputs '{"environment": "production"}'
+
+  # CLI adds optional fields:
+  # {"environment": "production", "optionalField": ""}
+  ```
+
+**Validation Examples:**
+
+```bash
+# ✓ Valid - all required fields provided
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs '{"environment": "production", "version": "1.2.3"}'
+
+# ✗ Invalid - missing required field
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs '{"environment": "production"}'
+# Error: Input validation failed:
+#   - Required input "version" is missing or empty
+
+# ✗ Invalid - boolean field has invalid value
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs '{"enabled": "yes"}'
+# Error: Input validation failed:
+#   - Input "enabled" must be true or false (got: yes)
+
+# ✓ Valid - optional fields can be omitted
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs '{"environment": "prod"}'
+# CLI automatically adds: {"environment": "prod", "optionalField": ""}
+```
+
+**Interactive Mode:**
+
+If `--inputs` is not provided, the CLI enters interactive mode and prompts for each input:
+
+```bash
+sembix workflow start --project-id proj_123 --workflow-id wf_456
+
+# Prompts appear:
+# ? environment (required): production
+# ? version (required): 1.2.3
+# ? dryRun (optional): [y/n]
+# ? notes (optional):
+```
 
 **`sembix workflow run list`**
 
@@ -786,6 +562,9 @@ sembix workflow run list
 # Filter by workflow
 sembix workflow run list --workflow-id wf_456
 
+# Filter by project
+sembix workflow run list --project-id proj_123
+
 # Filter by status
 sembix workflow run list --status RUNNING
 
@@ -829,1807 +608,336 @@ sembix workflow run stop --project-id proj_123 \
   --workflow-id wf_456 --run-id run_789
 ```
 
----
-
-### Global Options
-
-These options work with most commands:
-
-#### `--token <token>` or `-t <token>`
-
-Override the GitHub token from all other sources.
+## Common Workflows
 
+**Start and monitor a workflow:**
 ```bash
-sembix studio create --token ghp_custom_token
-```
-
-**Credential Priority:**
-1. `--token` flag (highest)
-2. `GITHUB_TOKEN` environment variable
-3. `~/.sembix/config` (created by `sembix configure`)
-4. `.env` file (lowest)
-
-#### `--profile <name>` or `-p <name>`
+# Interactive mode (easiest)
+sembix workflow start
 
-Specify which Studio profile to use for API commands.
+# Programmatic mode
+RUN_ID=$(sembix workflow start \
+  --project-id proj_123 \
+  --workflow-id wf_456 \
+  --inputs '{"env":"production"}' \
+  | jq -r '.runId')
 
-```bash
-sembix workflow start --profile production
+# Watch until completion
+sembix workflow run status \
+  --workflow-id wf_456 \
+  --run-id $RUN_ID \
+  --watch
 ```
 
-#### `--output <format>` or `--pretty`
-
-Set output format for command results.
-
-**Values:**
-- `json` (default) - Machine-readable JSON
-- `pretty` - Pretty-printed JSON with colors
-- `text` - Human-readable text (where supported)
-
+**List recent failures:**
 ```bash
-sembix project list --output pretty
-# or shorthand:
-sembix project list --pretty
+sembix workflow run list --status FAILED --limit 10
 ```
 
-#### `--help` or `-h`
-
-Display help information for a command.
-
+**Use default project:**
 ```bash
-sembix --help
-sembix studio --help
-sembix studio create --help
-```
-
-#### `--version` or `-V`
-
-Display the CLI version.
+# Set default project once
+sembix profile set-default-project production proj_123
 
-```bash
-sembix --version
+# Now omit --project-id
+sembix workflow start --workflow-id wf_456
 ```
 
----
-
-### Environment Variables
-
-Configure the CLI via `.env` file or system environment variables:
-
-```env
-# GitHub Personal Access Token (required for deployment commands)
-GITHUB_TOKEN=ghp_your_token_here
-
-# Default GitHub organization (optional)
-DEFAULT_GITHUB_ORG=your-org
+**Use inputs from file:**
+```bash
+# Create inputs.json
+cat > inputs.json <<EOF
+{
+  "repositoryUrl": "https://github.com/acme/repo",
+  "branch": "main",
+  "environment": "production"
+}
+EOF
 
-# Studio API client credentials (for CI/CD)
-SEMBIX_CLIENT_ID=7a8b9c0d1e2f3g4h
-SEMBIX_CLIENT_SECRET=abcdef123456...
+# Use file
+sembix workflow start \
+  --project-id proj_123 \
+  --workflow-id wf_456 \
+  --inputs @inputs.json
 ```
 
 ---
 
-### Exit Codes
-
-- `0` - Success
-- `1` - Error (validation failure, API error, user cancellation)
-
----
-
-### <a name="sembix-studio-create-all-options"></a>`sembix studio create` - All Options
-
-For reference, here's the complete list of all 50+ CLI flags for `sembix studio create`:
-
-**General:**
-- `-t, --token <token>` - GitHub personal access token
-- `-c, --config <path>` - Path to YAML configuration file
-- `-r, --repo <repo>` - Target repository (owner/repo format)
-- `-e, --env <environment>` - Environment name
-
-**AWS Basic Configuration:**
-- `--aws-account-id <id>` - AWS Account ID (12 digits)
-- `--aws-region <region>` - AWS Region (e.g., us-east-1)
-- `--customer-role-arn <arn>` - GitHub Actions IAM role ARN
-- `--terraform-state-bucket <bucket>` - S3 bucket for Terraform state
-
-**Database:**
-- `--database-name <name>` - PostgreSQL database name
-- `--database-user <user>` - PostgreSQL database user
-
-**Networking:**
-- `--enable-vpc-endpoints <boolean>` - Enable VPC endpoints (true/false)
-- `--use-custom-networking <boolean>` - Use existing VPC (true/false)
-- `--vpc-cidr <cidr>` - VPC CIDR block (e.g., 10.0.0.0/16)
-- `--public-subnet-cidrs <json>` - Public subnet CIDRs (JSON array)
-- `--private-subnet-cidrs <json>` - Private subnet CIDRs (JSON array)
-- `--az-count <count>` - Number of AZs (2 or 3)
-- `--custom-vpc-id <id>` - Existing VPC ID
-- `--custom-public-subnet-ids <ids>` - Existing public subnet IDs (comma-separated)
-- `--custom-private-subnet-ids <ids>` - Existing private subnet IDs (comma-separated)
-
-**Security - Security Groups:**
-- `--use-custom-security-groups <boolean>` - Use custom security groups (true/false)
-- `--sg-workflow-engine <id>` - Workflow Engine security group ID
-- `--sg-aurora <id>` - Aurora database security group ID
-- `--sg-rds-proxy <id>` - RDS Proxy security group ID
-- `--sg-bff-ecs <id>` - BFF ECS service security group ID
-- `--sg-bastion <id>` - Bastion host security group ID
-- `--sg-bff-alb <id>` - BFF ALB security group ID
-
-**Security - IAM Roles:**
-- `--use-custom-iam-roles <boolean>` - Use custom IAM roles (true/false)
-- `--iam-workflow-engine-exec <arn>` - Workflow Engine execution role ARN
-- `--iam-workflow-engine-task <arn>` - Workflow Engine task role ARN
-- `--iam-bff-ecs-exec <arn>` - BFF ECS task execution role ARN
-- `--iam-bff-ecs-task <arn>` - BFF ECS task role ARN
-- `--iam-rds-proxy <arn>` - RDS Proxy role ARN
-- `--iam-studio-memory <arn>` - Studio Memory role ARN
-- `--iam-studio-notification <arn>` - Studio Notification role ARN
+# Global Configuration
 
-**TLS/DNS:**
-- `--cloudfront-domain <domain>` - CloudFront custom domain
-- `--cloudfront-cert-arn <arn>` - CloudFront SSL certificate ARN (must be in us-east-1)
-- `--bff-alb-cert-arn <arn>` - BFF ALB SSL certificate ARN
-- `--hosted-zone-id <id>` - Route53 hosted zone ID
+## `sembix configure`
 
-**Feature Flags:**
-- `--deploy-studio-memory <boolean>` - Deploy Studio Memory service (true/false)
-- `--deploy-studio-notifications <boolean>` - Deploy Studio Notifications (true/false)
-- `--enable-bff-waf <boolean>` - Enable WAF for BFF (true/false)
+Interactive configuration for GitHub credentials and Studio profiles.
 
-**Frontend:**
-- `--github-app-client-id <id>` - GitHub App OAuth client ID
-- `--github-app-name <name>` - GitHub App name
-- `--jira-client-id <id>` - Jira OAuth client ID
+```bash
+sembix configure
+```
 
-**Hub Integration (Step 9):**
-- `--skip-hub` - Skip Hub integration configuration
-- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN
-- `--hub-consumer-role <arn>` - Hub Consumer Role ARN
-- `--hub-admin-role <arn>` - Hub Admin Role ARN
-- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN
-- `--hub-appconfig-app-id <id>` - Hub AppConfig Application ID
-- `--hub-appconfig-env-id <id>` - Hub AppConfig Environment ID
-- `--hub-appconfig-profile-id <id>` - Hub AppConfig Profile ID
+Prompts for:
+1. GitHub Personal Access Token
+2. Default GitHub organization (optional)
+3. Optionally: Studio profile configuration
+   - Profile name
+   - Studio API URL
+   - Cognito User Pool ID, Client ID, Region, Domain
 
----
+Saves to `~/.sembix/config` with 0600 permissions.
 
-## Usage Examples
+## Environment Variables
 
-Real-world examples showing different ways to use the CLI.
+**GitHub (for environment management):**
+- `GITHUB_TOKEN` - GitHub Personal Access Token
+- `DEFAULT_GITHUB_ORG` - Default GitHub organization
 
-### Basic Usage Patterns
+**Studio (for environment interaction):**
+- `SEMBIX_DEFAULT_PROFILE` - Default Studio profile
+- `SEMBIX_CLIENT_ID` - M2M client ID (for CI/CD)
+- `SEMBIX_CLIENT_SECRET` - M2M client secret (for CI/CD)
 
-#### 1. Fully Interactive (Beginner-Friendly)
+**Profile Selection Priority:**
+1. `--profile` CLI flag (highest)
+2. `SEMBIX_DEFAULT_PROFILE` environment variable
+3. `default_profile` in `~/.sembix/config`
+4. First available profile (lowest)
 
-Perfect for first-time users:
+## Global Options
 
+**Output Formatting:**
 ```bash
-sembix studio create
+--output <format>    # json, pretty, or text
+--pretty             # Shorthand for --output pretty
 ```
 
-**What happens:**
-- Prompts for repository selection
-- Prompts for environment name
-- Walks through all 9 configuration steps with explanations
-- Creates environment with all settings
-
-#### 2. Specify Repository and Environment
-
-Fast setup when you know both values:
-
+**Examples:**
 ```bash
-sembix studio create production --repo acme-corp/sembix-deployment
+sembix project list --pretty
+sembix workflow list --output json
 ```
 
-**What happens:**
-- ✅ Validates repository exists
-- ✅ Validates environment name format
-- ✅ Checks environment doesn't already exist
-- Skips repository and name prompts
-- Walks through configuration steps
-- Creates environment
-
-#### 3. Using Config Files
-
-For repeatable, version-controlled setups:
-
+**Other:**
 ```bash
-# Create environment from config file
-sembix studio create --config production.yaml
-
-# Override specific values
-sembix studio create --config base.yaml \
-  --env custom-name \
-  --aws-account-id 123456789012
+--help, -h           # Show help
+--version, -V        # Show version
 ```
 
-### Common Workflows
+---
+
+# Troubleshooting
 
-#### Workflow 1: First-Time Setup (Learning Mode)
+## Authentication Issues
 
+**GitHub token required:**
 ```bash
-# Step 1: Configure credentials
 sembix configure
-
-# Step 2: Create environment interactively
-sembix studio create
-
-# Follow all prompts, read explanations...
-
-# Step 3: Deploy via GitHub Actions
-# Go to https://github.com/owner/repo/actions
-# Run deployment workflow
-# Copy Hub role ARNs from output
-
-# Step 4: Add Hub integration
-sembix studio add-hub
-
-# Select same repository and environment
-# Enter Hub role ARNs
 ```
 
-#### Workflow 2: Experienced User (Fast Mode)
+**GitHub token invalid:**
+1. Create new token at https://github.com/settings/tokens
+2. Required scopes: `repo`, `workflow`
+3. Run `sembix configure` to update
 
+**Studio authentication required:**
 ```bash
-# Create with known values
-sembix studio create prod --repo acme/deploy
-
-# Answer remaining prompts
-# ... deployment happens in GitHub Actions ...
-
-# Add Hub with known values
-sembix studio add-hub prod --repo acme/deploy
-
-# Enter Hub role ARNs
+sembix login --profile production
 ```
 
-#### Workflow 3: CI/CD / Automation
-
-For scripts and automation:
-
+**Studio token expired:**
 ```bash
-#!/bin/bash
-
-REPO="acme-corp/sembix-deployment"
-ENV="client-${CLIENT_NAME}-production"
-
-# Create environment (with config file)
-sembix studio create "${ENV}" \
-  --repo "${REPO}" \
-  --config base-config.yaml \
-  --token "${GITHUB_TOKEN}"
-
-# Later, after deployment...
-sembix studio add-hub "${ENV}" \
-  --repo "${REPO}" \
-  --token "${GITHUB_TOKEN}"
+sembix logout --profile production
+sembix login --profile production
 ```
 
-#### Workflow 4: Multiple Environments
+## Common Errors
 
-Setting up multiple environments for the same repository:
+**Repository not found:**
+- Verify repository name format: `owner/repo`
+- Check token has access to repository
+- For orgs, configure SSO authorization
 
+**Environment already exists:**
 ```bash
-# Production
-sembix studio create production --repo acme/deploy
-
-# Staging
-sembix studio create staging --repo acme/deploy
-
-# Development
-sembix studio create development --repo acme/deploy
+# Update existing environment
+sembix studio update production --repo owner/repo
 
-# List all environments
-sembix studio list acme/deploy
+# Or use different name
+sembix studio create production-v2 --repo owner/repo
 ```
 
-### Profile Management Examples
-
-#### Working with Multiple Studio Instances
+**Invalid environment name:**
+- Must be lowercase letters, numbers, hyphens
+- Minimum 3 characters
+- No spaces or special characters
 
+**Profile not found:**
 ```bash
-# Configure multiple profiles
-sembix configure  # Profile name: production
-sembix configure  # Profile name: staging
+sembix configure  # Add profile
+sembix profile list  # List available profiles
+```
 
-# Set default profile
-sembix profile set-default production
+**Workflow not found:**
+```bash
+sembix workflow list --project-id proj_123  # List available workflows
+sembix workflow start  # Use interactive mode
+```
 
-# Set default projects for each profile
-sembix profile set-default-project production proj_prod_123
-sembix profile set-default-project staging proj_stage_456
+**Client credentials not working:**
+1. Verify credentials have no extra spaces
+2. Check required scopes:
+   - `sembix-api/projects.read`
+   - `sembix-api/workflows.read`
+   - `sembix-api/workflows.execute`
+3. Test locally:
+   ```bash
+   export SEMBIX_CLIENT_ID="your-id"
+   export SEMBIX_CLIENT_SECRET="your-secret"
+   sembix login
+   ```
 
-# List all profiles
-sembix profile list
+## Getting Help
 
-# Login to each profile
-sembix login production
-sembix login staging
+```bash
+sembix --help                        # Global help
+sembix studio --help                 # Studio commands help
+sembix studio create --help          # Specific command help
+sembix workflow start --help         # Workflow command help
 
-# Use different profiles for different workflows
-sembix workflow start --profile production --workflow-id wf_456
-sembix workflow start --profile staging --workflow-id wf_789
+sembix --version                     # Check CLI version
+sembix profile list                  # Check profile status
+sembix studio list                   # Verify GitHub access
 ```
 
-### Error Handling Examples
-
-#### Missing GitHub Token
+---
 
-```bash
-$ sembix studio create
-✗ GitHub token is required. Please provide it using one of these methods:
-  1. Run: sembix configure
-  2. Set GITHUB_TOKEN environment variable
-  3. Pass --token flag to the command
-```
+# Development
 
-**Solution:**
+## Project Structure
 
-```bash
-sembix configure
+```
+sembix-cli/
+├── src/
+│   ├── commands/              # Command implementations
+│   ├── prompts/               # Interactive prompts
+│   ├── services/              # Cognito auth, GitHub API
+│   ├── utils/                 # Utilities (config, UI)
+│   ├── types.ts               # TypeScript types
+│   ├── config-schema.ts       # Zod schemas
+│   └── index.ts               # CLI entry point
+├── config.example.yaml        # Example config file
+└── package.json
 ```
 
-#### Invalid Repository Format
+## Scripts
 
 ```bash
-$ sembix studio create prod --repo invalid_format
-✗ Invalid repository format. Use: owner/repo
+npm run build       # Compile TypeScript
+npm run dev         # Run with tsx (development)
+npm run type-check  # Type check only
+npm test            # Run tests
 ```
 
-#### Repository Not Found
+## Adding Commands
 
-```bash
-$ sembix studio create prod --repo nonexistent/repo
-✗ Repository 'nonexistent/repo' not found or not accessible.
+1. Create file in `src/commands/`
+2. Add prompts in `src/prompts/` if needed
+3. Register command in `src/index.ts`
+4. Add types to `src/types.ts`
+5. Add validation to `src/config-schema.ts`
 
-💡 Make sure:
-   • The repository name is correct (owner/repo)
-   • Your GitHub token has access to this repository
-```
+---
 
-#### Invalid Environment Name
+# Complete Studio Options
 
-```bash
-$ sembix studio create "My Environment" --repo acme/deploy
-✗ Invalid environment name. Must be lowercase letters, numbers, and hyphens (min 3 chars).
-```
+<a name="complete-studio-options"></a>
 
-#### Environment Already Exists
+All options for `sembix studio create` and `sembix studio update`:
 
-```bash
-$ sembix studio create production --repo acme/deploy
-✗ Environment 'production' already exists in acme/deploy
+**General:**
+- `-t, --token <token>` - GitHub token
+- `-c, --config <path>` - YAML config file
+- `-r, --repo <repo>` - Repository (owner/repo)
+- `-e, --env <name>` - Environment name
 
-💡 Tip:
-   • Use a different environment name
-   • Or update the existing environment with: sembix studio update
-```
+**AWS:**
+- `--aws-account-id <id>` - AWS Account ID (12 digits)
+- `--aws-region <region>` - AWS Region
+- `--customer-role-arn <arn>` - GitHub Actions IAM role ARN
+- `--terraform-state-bucket <bucket>` - Terraform state S3 bucket
 
-#### Authentication Errors (Studio API)
+**Database:**
+- `--database-name <name>` - PostgreSQL database name
+- `--database-user <user>` - PostgreSQL database user
 
-```bash
-# Error: Token expired
-$ sembix workflow start
-✗ Authentication required. Please run: sembix login
-```
+**Networking:**
+- `--enable-vpc-endpoints <boolean>` - Enable VPC endpoints
+- `--use-custom-networking <boolean>` - Use existing VPC
+- `--vpc-cidr <cidr>` - VPC CIDR block
+- `--public-subnet-cidrs <json>` - Public subnet CIDRs (JSON array)
+- `--private-subnet-cidrs <json>` - Private subnet CIDRs (JSON array)
+- `--az-count <count>` - Number of AZs (2 or 3)
+- `--custom-vpc-id <id>` - Existing VPC ID
+- `--custom-public-subnet-ids <ids>` - Existing public subnet IDs (comma-separated)
+- `--custom-private-subnet-ids <ids>` - Existing private subnet IDs (comma-separated)
 
-**Solution:**
+**Security Groups:**
+- `--use-custom-security-groups <boolean>` - Use custom security groups
+- `--sg-workflow-engine <id>` - Workflow Engine SG
+- `--sg-aurora <id>` - Aurora SG
+- `--sg-rds-proxy <id>` - RDS Proxy SG
+- `--sg-bff-ecs <id>` - BFF ECS SG
+- `--sg-bastion <id>` - Bastion SG
+- `--sg-bff-alb <id>` - BFF ALB SG
+- `--sg-semantic-event-engine <id>` - Semantic Event Engine SG
+
+**IAM Roles:**
+- `--use-custom-iam-roles <boolean>` - Use custom IAM roles
+- `--iam-workflow-engine-exec <arn>` - Workflow Engine execution role ARN
+- `--iam-workflow-engine-task <arn>` - Workflow Engine task role ARN
+- `--iam-bff-ecs-exec <arn>` - BFF ECS execution role ARN
+- `--iam-bff-ecs-task <arn>` - BFF ECS task role ARN
+- `--iam-semantic-event-engine-exec <arn>` - Semantic Event Engine execution role ARN
+- `--iam-semantic-event-engine-task <arn>` - Semantic Event Engine task role ARN
+- `--iam-rds-proxy <arn>` - RDS Proxy role ARN
+- `--iam-studio-memory <arn>` - Studio Memory role ARN
+- `--iam-studio-notification <arn>` - Studio Notification role ARN
 
-```bash
-sembix login --profile production
-```
+**TLS/DNS:**
+- `--cloudfront-domain <domain>` - CloudFront custom domain
+- `--cloudfront-cert-arn <arn>` - CloudFront certificate ARN (us-east-1)
+- `--bff-alb-cert-arn <arn>` - BFF ALB certificate ARN
+- `--hosted-zone-id <id>` - Route53 hosted zone ID
 
-### Workflow Execution Patterns
+**Features:**
+- `--deploy-studio-memory <boolean>` - Deploy Studio Memory service
+- `--deploy-studio-notifications <boolean>` - Deploy Studio Notifications
+- `--enable-bff-waf <boolean>` - Enable WAF for BFF
 
-#### Start and Monitor a Workflow
+**Frontend:**
+- `--github-app-client-id <id>` - GitHub App OAuth client ID
+- `--github-app-name <name>` - GitHub App name
+- `--jira-client-id <id>` - Jira OAuth client ID
 
-```bash
-# Start workflow and capture run ID
-RUN_ID=$(sembix workflow start \
-  --project-id proj_123 \
-  --workflow-id wf_456 \
-  --inputs '{"env":"production"}' \
-  | grep "Run ID" | awk '{print $3}')
+**Hub Integration:**
+- `--skip-hub` - Skip Hub integration
+- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN
+- `--hub-consumer-role <arn>` - Hub Consumer Role ARN
+- `--hub-admin-role <arn>` - Hub Admin Role ARN
+- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN
+- `--hub-appconfig-app-id <id>` - Hub AppConfig Application ID
+- `--hub-appconfig-env-id <id>` - Hub AppConfig Environment ID
+- `--hub-appconfig-profile-id <id>` - Hub AppConfig Profile ID
 
-# Watch until completion
-sembix workflow run status \
-  --workflow-id wf_456 \
-  --run-id $RUN_ID \
-  --watch
-```
+---
 
-#### List Recent Failures
+# License
 
-```bash
-sembix workflow run list \
-  --status FAILED \
-  --limit 10
-```
+Proprietary - Sembix AI
 
-#### Monitor Specific Workflow
-
-```bash
-sembix workflow run list \
-  --workflow-id wf_456 \
-  --status RUNNING
-```
-
-#### Using Workflow Inputs from Files
-
-```bash
-# Create inputs.json
-cat > inputs.json <<EOF
-{
-  "environment": "production",
-  "version": "1.2.3",
-  "config": {
-    "debug": false,
-    "replicas": 3
-  }
-}
-EOF
-
-# Use file in workflow start
-sembix workflow start \
-  --project-id proj_123 \
-  --workflow-id wf_456 \
-  --inputs @inputs.json
-```
-
-### Best Practices
-
-#### ✅ DO
-
-- Use `--repo` and `--env` for repeated operations
-- Validate with `sembix studio list` first
-- Use descriptive environment names (client-production, staging-v2)
-- Store GitHub token in `~/.sembix/config` via `sembix configure`
-- Keep environment names lowercase with hyphens
-- Use config files for version-controlled setups
-- Set default projects per profile for faster workflow execution
-- Use `--pretty` for human-readable output
-- Use `--watch` to monitor long-running workflows
-
-#### ❌ DON'T
-
-- Don't use uppercase in environment names
-- Don't use spaces or special characters
-- Don't share your GitHub token or client credentials
-- Don't create environments without verifying repo access first
-- Don't forget to run deployment between create and add-hub
-- Don't commit sensitive credentials to git
-- Don't use production credentials in development
-
-### CI/CD Integration Examples
-
-#### GitHub Actions
-
-```yaml
-name: Deploy via Sembix
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Install Sembix CLI
-        run: npm install -g @sembix/cli
-
-      - name: Start Deployment Workflow
-        env:
-          SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
-          SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
-        run: |
-          sembix workflow start \
-            --profile production \
-            --project-id ${{ vars.PROJECT_ID }} \
-            --workflow-id ${{ vars.WORKFLOW_ID }} \
-            --inputs '{"version":"${{ github.sha }}"}'
-```
-
-#### GitLab CI
-
-```yaml
-deploy:
-  image: node:20
-  script:
-    - npm install -g @sembix/cli
-    - |
-      sembix workflow start \
-        --profile production \
-        --project-id ${PROJECT_ID} \
-        --workflow-id ${WORKFLOW_ID} \
-        --inputs "{\"version\":\"${CI_COMMIT_SHA}\"}"
-  variables:
-    SEMBIX_CLIENT_ID: ${M2M_CLIENT_ID}
-    SEMBIX_CLIENT_SECRET: ${M2M_CLIENT_SECRET}
-```
-
-### Output Formatting Examples
-
-```bash
-# JSON output (default) - for scripts/automation
-sembix project list --output json
-
-# Pretty JSON - for human reading
-sembix project list --output pretty
-# or shorthand:
-sembix project list --pretty
-
-# Text output - for terminal display
-sembix project list --output text
-```
-
-### Quick Reference Cheat Sheet
-
-```bash
-# GitHub Deployment
-sembix configure                              # First-time setup
-sembix studio create                          # Interactive create
-sembix studio create prod --repo owner/repo   # Quick create
-sembix studio add-hub prod --repo owner/repo  # Add Hub integration
-sembix studio list owner/repo                 # List environments
-
-# Studio API
-sembix configure                              # Configure profile
-sembix login                                  # Authenticate
-sembix profile list                           # List profiles
-sembix profile set-default-project prod proj_123  # Set default project
-
-# Projects & Workflows
-sembix project list                           # List projects
-sembix workflow start                         # Start workflow (interactive)
-sembix workflow run list                      # List workflow runs
-sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
-
-# Troubleshooting
-sembix --version                              # Check CLI version
-sembix studio list owner/repo                 # Verify repo access
-sembix profile list                           # Check profile status
-sembix login --profile production             # Re-authenticate
-```
-
-## Studio CLI
-
-The Sembix CLI now supports direct integration with Sembix Studio instances for workflow execution and management.
-
-### Studio Configuration
-
-Configure a Studio profile to connect to a Sembix Studio instance using the unified configure command:
-
-```bash
-sembix configure
-```
-
-This interactive command will first prompt for GitHub credentials, then optionally prompt you to configure a Studio profile with:
-- **Profile name** (default: "default")
-- **Studio API URL** (e.g., https://studio.example.com)
-- **Cognito User Pool ID** (e.g., us-east-1_ABC123)
-- **Cognito Client ID**
-- **Cognito Region**
-- **Cognito Domain** (e.g., https://auth.example.com)
-
-### Authentication
-
-The Sembix CLI supports two authentication methods:
-1. **Browser-based OAuth** - For developers on local machines
-2. **Client Credentials** - For CI/CD pipelines and automated workflows
-
-#### Local Development (Browser-based OAuth)
-
-Authenticate with a Studio instance using browser-based OAuth:
-
-```bash
-# Login to default profile
-sembix login
-
-# Login to specific profile
-sembix login --profile production
-
-# Logout from profile
-sembix logout --profile production
-
-# Logout from all profiles
-sembix logout --all
-```
-
-**What happens during login:**
-1. Opens your default browser to Cognito hosted UI
-2. You authenticate with your Studio credentials
-3. Tokens are securely stored in `~/.sembix/tokens/<profile>.json`
-4. Tokens are automatically refreshed when expired
-
-#### CI/CD Pipelines (Client Credentials)
-
-For automated workflows, use OAuth 2.0 Client Credentials flow:
-
-**Prerequisites:**
-- Obtain M2M (machine-to-machine) client credentials from your administrator:
-  - Client ID (e.g., `7a8b9c0d1e2f3g4h`)
-  - Client Secret (keep secure!)
-  - Required OAuth scopes:
-    - `sembix-api/projects.read` - List projects
-    - `sembix-api/workflows.read` - View workflows and runs
-    - `sembix-api/workflows.execute` - Start/stop workflows
-
-**Setup:**
-
-1. **Add credentials to your CI/CD secrets:**
-
-   GitHub Actions:
-   ```yaml
-   # In repository settings → Secrets and variables → Actions
-   SEMBIX_CLIENT_ID=7a8b9c0d1e2f3g4h5i6j7k8l
-   SEMBIX_CLIENT_SECRET=abcdef123456...
-   ```
-
-   GitLab CI:
-   ```yaml
-   # In repository settings → CI/CD → Variables
-   SEMBIX_CLIENT_ID=7a8b9c0d1e2f3g4h5i6j7k8l
-   SEMBIX_CLIENT_SECRET=abcdef123456...
-   ```
-
-2. **Use in your workflow:**
-
-   ```yaml
-   - name: Start workflow
-     env:
-       SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
-       SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
-     run: |
-       sembix workflow start \
-         --project-id abc123 \
-         --workflow-id def456 \
-         --inputs '{"key": "value"}'
-   ```
-
-**How it works:**
-- The CLI automatically detects `SEMBIX_CLIENT_ID` and `SEMBIX_CLIENT_SECRET` environment variables
-- Authenticates using OAuth 2.0 Client Credentials flow
-- No browser or interactive login needed
-- Tokens obtained on-demand (not stored)
-
-**Testing credentials locally:**
-```bash
-export SEMBIX_CLIENT_ID="your-client-id"
-export SEMBIX_CLIENT_SECRET="your-client-secret"
-
-# Verify credentials work
-sembix login
-# Output: "Client credentials detected... Client credentials are valid!"
-```
-
-**Security best practices:**
-- Never commit credentials to git
-- Use CI/CD secret management (GitHub Secrets, AWS Secrets Manager, etc.)
-- Rotate client secrets regularly (every 90 days recommended)
-- Use separate credentials for different environments (dev, staging, prod)
-
-See the [CI/CD Setup Guide](./docs/CI-CD-SETUP.md) for complete examples and troubleshooting.
-
-### Profile Management
-
-Manage Studio profiles:
-
-```bash
-# List all profiles
-sembix profile list
-
-# Show profile details
-sembix profile show production
-
-# Set default profile
-sembix profile set-default production
-
-# Delete profile
-sembix profile delete staging
-```
-
-**Profile list output:**
-```
-  Sembix Studio Profiles
-
-  Name         API URL                      Auth Status
-  ──────────────────────────────────────────────────────
-* default      https://studio.example.com   ✓ Authenticated
-  production   https://prod.example.com     ✗ Not authenticated
-  staging      https://staging.example.com  ✓ Authenticated
-
-* = default profile
-```
-
-### Profile Project Defaults
-
-Set default projects for profiles to avoid specifying `--project-id` repeatedly.
-
-**Set default project:**
-```bash
-sembix profile set-default-project <profile> <project-id>
-
-# Example
-sembix profile set-default-project production proj_abc123
-```
-
-**Get default project:**
-```bash
-sembix profile get-default-project <profile>
-
-# Example
-sembix profile get-default-project production
-# Output: proj_abc123
-```
-
-**Clear default project:**
-```bash
-sembix profile clear-default-project <profile>
-
-# Example
-sembix profile clear-default-project production
-```
-
-**Usage with workflow commands:**
-```bash
-# Set default project
-sembix profile set-default-project production proj_abc123
-
-# Now you can omit --project-id
-sembix workflow start --workflow-id wf_456 --inputs '{...}'
-# Uses proj_abc123 automatically
-```
-
-### Project Management
-
-List and view projects in your Studio instance.
-
-**List all projects:**
-```bash
-# List all projects
-sembix project list
-
-# Filter by name
-sembix project list --name "My Project"
-
-# Filter by IDs
-sembix project list --ids "proj_123,proj_456"
-
-# With specific profile
-sembix project list --profile production
-```
-
-**Show project details:**
-```bash
-sembix project show --project-id proj_abc123
-
-# With specific profile
-sembix project show --project-id proj_abc123 --profile production
-```
-
-**Output:**
-```json
-{
-  "projectId": "proj_abc123",
-  "name": "My Project",
-  "description": "Project description",
-  "state": "ACTIVE",
-  "createdAt": "2024-01-15T10:00:00Z",
-  "workflowPackConfigured": true
-}
-```
-
-### Workflow Operations
-
-Execute and manage workflows:
-
-#### Start a Workflow
-
-```bash
-# Interactive mode (prompts for project, workflow, and inputs)
-sembix workflow start
-
-# With project ID and workflow ID
-sembix workflow start --project-id abc123 --workflow-id def456
-
-# With workflow name instead of ID
-sembix workflow start --project-id abc123 --workflow-name "Deploy to Production"
-
-# Start with inline JSON inputs
-sembix workflow start --project-id abc123 --workflow-id def456 --inputs '{"key": "value"}'
-
-# Start with inputs from file
-sembix workflow start --project-id abc123 --workflow-id def456 --inputs @inputs.json
-
-# Non-interactive mode (skip prompts)
-sembix workflow start --project-id abc123 --workflow-id def456 --no-interactive
-
-# Using default project (set via profile set-default-project)
-sembix workflow start --workflow-id def456 --inputs '{...}'
-
-# Start with workspace and issue context
-sembix workflow start \
-  --project-id abc123 \
-  --workflow-id def456 \
-  --workspace-id ws-789 \
-  --issue-id issue-101 \
-  --inputs '{"param": "value"}'
-
-# Use specific profile
-sembix workflow start \
-  --profile production \
-  --project-id abc123 \
-  --workflow-id def456 \
-  --inputs '{"key": "value"}'
-```
-
-**Example inputs.json:**
-```json
-{
-  "inputVariables": {
-    "repositoryUrl": "https://github.com/acme/repo",
-    "branch": "main"
-  },
-  "workspaceId": "ws-123",
-  "workspaceName": "My Workspace",
-  "issueId": "issue-456",
-  "issueKey": "PROJ-123"
-}
-```
-
-#### Check Workflow Status
-
-```bash
-# Get current status
-sembix workflow run status --workflow-id wf_456 --run-id run_789
-
-# Watch workflow until completion (polls every 5 seconds)
-sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
-```
-
-**Status output:**
-```
-  Workflow Run Status
-
-  Run ID:       run-789
-  Workflow ID:  def456
-  Status:       RUNNING
-  Progress:     45%
-  Created:      2024-01-15 10:30:00
-  Creator:      user-123
-```
-
-#### List Workflow Runs
-
-```bash
-# List workflow instances (definitions)
-sembix workflow list
-
-# Filter by project
-sembix workflow list --project-id proj_123
-
-# Filter by template IDs
-sembix workflow list --workflow-template-ids "tmpl_1,tmpl_2"
-
-# Show workflow instance details
-sembix workflow show --project-id proj_123 --workflow-id wf_456
-
-# List workflow runs (executions) - excludes subflows by default
-sembix workflow run list
-
-# Filter by workflow
-sembix workflow run list --workflow-id wf_456
-
-# Filter by project
-sembix workflow run list --project-id proj_123
-
-# Filter by status
-sembix workflow run list --status RUNNING
-
-# Include sub-workflow runs
-sembix workflow run list --include-subflows
-
-# Filter to top-level runs only
-sembix workflow run list --parent-id NULL
-
-# Pagination
-sembix workflow run list --limit 20 --offset 10
-
-# Show specific run details
-sembix workflow run show --workflow-id wf_456 --run-id run_789
-
-# Watch run details until completion
-sembix workflow run show --workflow-id wf_456 --run-id run_789 --watch
-```
-
-**List output:**
-```
-  Workflow Runs
-
-  Run ID    Workflow ID  Status      Progress  Created
-  ────────────────────────────────────────────────────────
-  run-789   def456       RUNNING     45%       2 hours ago
-  run-788   def456       COMPLETED   100%      1 day ago
-  run-787   abc123       FAILED      30%       2 days ago
-
-  Showing 1-3 of 15 results
-```
-
-#### Stop a Workflow Run
-
-```bash
-sembix workflow run stop --project-id proj_123 --workflow-id wf_456 --run-id run_789
-```
-
-### Common Workflow Patterns
-
-**1. Start and monitor a workflow:**
-```bash
-# Start workflow and capture run ID
-RUN_ID=$(sembix workflow start \
-  --project-id abc123 \
-  --workflow-id def456 \
-  --inputs '{"key": "value"}' \
-  | grep "Run ID" | awk '{print $3}')
-
-# Watch until completion
-sembix workflow run status \
-  --workflow-id def456 \
-  --run-id $RUN_ID \
-  --watch
-```
-
-**2. List recent failures:**
-```bash
-sembix workflow run list \
-  --status FAILED \
-  --limit 10
-```
-
-**3. Monitor specific workflow:**
-```bash
-sembix workflow run list \
-  --workflow-id def456 \
-  --status RUNNING
-```
-
-### Output Formatting
-
-Control output format for all commands using global flags.
-
-**Available formats:**
-- `json` (default) - Machine-readable JSON output
-- `pretty` - Pretty-printed JSON with colors and indentation
-- `text` - Human-readable text output (where applicable)
-
-**Usage:**
-
-```bash
-# JSON output (default)
-sembix workflow run list --workflow-id wf_456
-
-# Pretty-printed JSON
-sembix workflow run list --workflow-id wf_456 --output pretty
-# or shorthand:
-sembix workflow run list --workflow-id wf_456 --pretty
-
-# Text output
-sembix project list --output text
-```
-
-**Examples:**
-
-```bash
-# JSON (default) - for scripts/automation
-$ sembix project show --project-id proj_123
-{"projectId":"proj_123","name":"My Project","state":"ACTIVE",...}
-
-# Pretty JSON - for human reading
-$ sembix project show --project-id proj_123 --pretty
-{
-  "projectId": "proj_123",
-  "name": "My Project",
-  "state": "ACTIVE",
-  ...
-}
-
-# Text - for terminal display
-$ sembix project list --output text
-Projects:
-  1. My Project (proj_123) - ACTIVE
-  2. Another Project (proj_456) - ACTIVE
-```
-
-**Global flags:**
-- `--output <format>` - Set output format: json, pretty, or text
-- `--pretty` - Shorthand for `--output pretty`
-
-### Error Handling
-
-**Authentication errors:**
-```bash
-# If you see "Authentication required" or "Token expired"
-sembix login --profile production
-```
-
-**Profile not found:**
-```bash
-# Configure the profile first
-sembix configure
-# Choose to configure Studio profile with name: production
-```
-
-**Invalid inputs:**
-```bash
-# Validate your JSON syntax
-cat inputs.json | jq .
-```
-
-## Workflow
-
-### Two-Phased Deployment Process
-
-```
-╔═══════════════════════════════════════════════════════════════════╗
-║                    PHASE 1: BOOTSTRAP DEPLOYMENT                  ║
-╚═══════════════════════════════════════════════════════════════════╝
-
-┌─────────────────────────────────────────────────┐
-│  1. Create Environment (Skip Hub)               │
-│     sembix studio create --skip-hub             │
-│     • Configure environment (Steps 1-8)         │
-│     • Skip Hub integration (Step 9)             │
-│     • Creates GitHub Actions environment        │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│  2. Bootstrap Deployment via GitHub Actions     │
-│     • Go to repo → Actions → Run workflow       │
-│     • Deploys initial Terraform infrastructure  │
-│     • Creates IAM roles in your AWS account     │
-│     • Copy IAM ARNs from deployment output      │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│  3. Coordinate with Sembix Support              │
-│     • Send IAM ARNs to Sembix support           │
-│     • Wait for Sembix to configure Hub          │
-│     • Receive Hub role ARNs from support:       │
-│       - Hub Engine Execution Role ARN           │
-│       - Hub Consumer Role ARN                   │
-│       - Hub Admin Role ARN                      │
-│       - Hub AppConfig Role ARN + IDs            │
-└─────────────────────────────────────────────────┘
-
-╔═══════════════════════════════════════════════════════════════════╗
-║              PHASE 2: HUB INTEGRATION & FULL DEPLOYMENT           ║
-╚═══════════════════════════════════════════════════════════════════╝
-
-┌─────────────────────────────────────────────────┐
-│  4. Add Hub Integration                         │
-│     sembix studio add-hub <environment>         │
-│     • Provide Hub role ARNs from support        │
-│     • Updates GitHub Actions environment        │
-│     • Configures cross-account access           │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│  5. Full Deployment via GitHub Actions          │
-│     • Go to repo → Actions → Run workflow       │
-│     • Completes full Sembix Studio deployment   │
-│     • Enables Hub cross-account access          │
-│     • ✅ Studio environment fully operational   │
-└─────────────────────────────────────────────────┘
-```
-
-## Configuration Priority
-
-The CLI follows this priority chain for configuration values:
-
-```
-CLI Flags > Config File > Interactive Prompts > Defaults
-```
-
-**Examples:**
-
-```bash
-# Config file provides base, CLI flags override specific values
-sembix studio create --config base.yaml --env custom-name
-
-# Interactive prompts only for missing values
-sembix studio create --repo acme/deploy --aws-account-id 123456789012
-# Will prompt for all other fields
-
-# Fully automated (no prompts)
-sembix studio create --config complete.yaml
-# No prompts if config file is complete
-```
-
-## Config File Reference
-
-See [`config.example.yaml`](./config.example.yaml) for a complete, documented example.
-
-**Minimal config:**
-
-```yaml
-repository:
-  owner: acme-corp
-  repo: sembix-deployment
-
-environmentName: production
-awsAccountId: "123456789012"
-awsRegion: us-east-1
-customerRoleArn: arn:aws:iam::123456789012:role/GitHubActionsDeployRole
-terraformStateBucket: my-terraform-state-bucket
-
-database:
-  name: sembix_studio
-  user: sembix_studio_user
-
-tls:
-  cloudfrontDomain: studio.acme.com
-  cloudfrontCertArn: arn:aws:acm:us-east-1:123456789012:certificate/abc123
-  bffAlbCertificateArn: arn:aws:acm:us-east-1:123456789012:certificate/def456
-  hostedZoneId: Z1234567890ABC
-
-frontend:
-  githubAppClientId: Iv1.0123456789abcdef
-  githubAppName: sembix-studio-app
-  jiraClientId: abc123def456
-```
-
-**Complete config with all options:**
-
-```yaml
-# See config.example.yaml for:
-# - Networking configuration (VPC, subnets)
-# - Custom security groups
-# - Custom IAM roles
-# - Feature flags
-# - Hub integration
-# - All advanced options
-```
-
-## Use Cases
-
-### 1. First-Time Setup (Interactive Learning)
-
-Perfect for understanding all configuration options:
-
-```bash
-sembix studio create
-```
-
-Follow all 9 steps with detailed explanations.
-
-### 2. Rapid Iteration (Config Files)
-
-For creating multiple similar environments:
-
-```bash
-# Create base config once
-cp config.example.yaml clients/base.yaml
-# Edit base.yaml with common settings
-
-# Create client-specific environments
-sembix studio create --config clients/base.yaml --env client-abc-prod
-sembix studio create --config clients/base.yaml --env client-xyz-prod
-```
-
-### 3. CI/CD Automation
-
-For automated environment creation in pipelines:
-
-```bash
-#!/bin/bash
-CLIENT_NAME=$1
-sembix studio create "${CLIENT_NAME}-production" \
-  --config ci/base-config.yaml \
-  --token "$GITHUB_TOKEN" \
-  --aws-account-id "$CLIENT_AWS_ACCOUNT" \
-  --cloudfront-domain "studio.${CLIENT_NAME}.example.com"
-```
-
-### 4. Infrastructure as Code
-
-Version control your environment configurations:
-
-```
-configs/
-├── base.yaml              # Common settings
-├── production.yaml        # Production overrides
-├── staging.yaml           # Staging overrides
-└── development.yaml       # Dev overrides
-```
-
-```bash
-# Create from version-controlled configs
-sembix studio create --config configs/production.yaml
-sembix studio create --config configs/staging.yaml
-```
-
-### 5. Hub Integration After Deployment
-
-Add Hub configuration after initial deployment:
-
-```bash
-# Step 1: Create without Hub
-sembix studio create production --repo acme/deploy --skip-hub
-
-# Step 2: Deploy and get Hub ARNs
-
-# Step 3: Add Hub integration
-sembix studio update production --repo acme/deploy \
-  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine \
-  --hub-consumer-role arn:aws:iam::123456789012:role/HubConsumer \
-  --hub-admin-role arn:aws:iam::123456789012:role/HubAdmin
-```
-
-## Development
-
-### Project Structure
-
-```
-sembix-cli/
-├── src/
-│   ├── commands/              # Command implementations
-│   │   ├── setup.ts           # Environment create command
-│   │   ├── update.ts          # Environment update command
-│   │   └── hub-integration.ts # Deprecated hub command
-│   ├── prompts/               # Interactive prompts
-│   │   ├── environment-setup.ts     # Main setup prompts
-│   │   ├── hub-integration-step.ts  # Hub integration prompts
-│   │   └── hub-integration.ts       # Deprecated hub prompts
-│   ├── utils/                 # Utility modules
-│   │   ├── github.ts          # GitHub API client
-│   │   ├── ui.ts              # Terminal UI utilities
-│   │   └── config-loader.ts   # Config file loading & merging
-│   ├── types.ts               # TypeScript types
-│   ├── config-schema.ts       # Zod schemas for config validation
-│   ├── config.ts              # Configuration management
-│   └── index.ts               # CLI entry point
-├── config.example.yaml        # Example config file
-├── package.json
-├── tsconfig.json
-├── .env.example
-└── README.md
-```
-
-### Scripts
-
-```bash
-npm run build       # Compile TypeScript to JavaScript
-npm run dev         # Run in development mode with tsx
-npm run type-check  # Type check without emitting files
-```
-
-### Adding New Commands
-
-1. Create a new file in `src/commands/`
-2. Implement the command logic
-3. Add prompts in `src/prompts/` if needed
-4. Register the command in `src/index.ts`
-
-Example:
-
-```typescript
-// src/commands/my-command.ts
-export async function myCommand(githubToken: string, options: Record<string, any>): Promise<void> {
-  // Command implementation
-}
-
-// src/index.ts
-studio
-  .command('my-command')
-  .description('Description of my command')
-  .option('-r, --repo <repo>', 'Target repository')
-  .action(async (options) => {
-    const { myCommand } = await import('./commands/my-command.js');
-    await myCommand(config.githubToken, options);
-  });
-```
-
-## Troubleshooting
-
-Comprehensive troubleshooting guide for common issues.
-
-### Authentication Issues
-
-#### "GitHub token is required"
-
-**Error:**
-```
-✗ GitHub token is required. Please provide it using one of these methods:
-  1. Run: sembix configure
-  2. Set GITHUB_TOKEN environment variable
-  3. Pass --token flag to the command
-```
-
-**Solution:**
-```bash
-# Easiest method (recommended)
-sembix configure
-
-# Alternative: Create .env file
-echo "GITHUB_TOKEN=ghp_your_token_here" > .env
-
-# Or pass token directly
-sembix studio create --token ghp_your_token_here
-```
-
-#### "Failed to create environment: Bad credentials"
-
-**Cause:** GitHub token is invalid or missing required scopes.
-
-**Solution:**
-1. Create a new Personal Access Token at: https://github.com/settings/tokens
-2. Required scopes:
-   - ✅ `repo` (all sub-scopes)
-   - ✅ `workflow`
-3. Update your configuration:
-```bash
-sembix configure
-```
-
-#### "Authentication required" (Studio API)
-
-**Error:**
-```
-✗ Authentication required. Please run: sembix login
-```
-
-**Solution:**
-```bash
-# Login with default profile
-sembix login
-
-# Or specific profile
-sembix login --profile production
-
-# If tokens expired, re-authenticate
-sembix logout --profile production
-sembix login --profile production
-```
-
-#### Browser did not open (Studio login)
-
-**Error:** Browser window doesn't open during `sembix login`
-
-**Solution:**
-1. Manually copy the URL displayed in terminal
-2. Open it in your browser
-3. Complete authentication within 5 minutes
-4. If timeout occurs, run `sembix login` again
-
-### GitHub API Issues
-
-#### "No repositories found"
-
-**Cause:** GitHub token doesn't have access to repositories.
-
-**Solution:**
-1. Verify token has `repo` scope
-2. Check organization access:
-   - GitHub Settings → Personal Access Tokens → Your token → Configure SSO (if applicable)
-   - Click "Authorize" for your organization
-3. Verify repository name is correct (use `owner/repo` format)
-
-#### "Repository not found or not accessible"
-
-**Error:**
-```
-✗ Repository 'owner/repo' not found or not accessible.
-```
-
-**Solution:**
-```bash
-# Verify repository name format
-sembix studio list  # Lists accessible repositories
-
-# Check token permissions
-# Go to: https://github.com/settings/tokens
-# Ensure 'repo' scope is enabled
-
-# If using organization repos, configure SSO
-```
-
-#### "Environment already exists"
-
-**Error:**
-```
-✗ Environment 'production' already exists in owner/repo
-```
-
-**Solution:**
-```bash
-# Option 1: Update existing environment
-sembix studio update production --repo owner/repo
-
-# Option 2: Use different environment name
-sembix studio create production-v2 --repo owner/repo
-
-# Option 3: Delete and recreate (not recommended)
-# Delete manually in GitHub UI, then:
-sembix studio create production --repo owner/repo
-```
-
-### Studio API Issues
-
-#### "Profile not found"
-
-**Error:**
-```
-✗ Profile 'production' not found
-```
-
-**Solution:**
-```bash
-# List configured profiles
-sembix profile list
-
-# Configure the profile
-sembix configure
-# Choose to configure Studio profile with name: production
-```
-
-#### "Cannot connect to Studio API"
-
-**Error:** Connection refused or timeout errors
-
-**Solution:**
-1. Verify API URL in profile configuration:
-```bash
-sembix profile show production
-```
-
-2. Check network connectivity:
-```bash
-curl https://studio.example.com/health
-```
-
-3. Reconfigure profile if URL is incorrect:
-```bash
-sembix configure
-# Use same profile name to update
-```
-
-#### "401 Unauthorized"
-
-**Error:** API returns 401 error
-
-**Solution:**
-```bash
-# Token expired - re-authenticate
-sembix login --profile production
-
-# If still failing, logout and login again
-sembix logout --profile production
-sembix login --profile production
-```
-
-#### "Workflow not found"
-
-**Error:**
-```
-✗ Workflow 'wf_456' not found
-```
-
-**Solution:**
-```bash
-# List available workflows
-sembix workflow list --project-id proj_123
-
-# Or use interactive mode to search
-sembix workflow start
-```
-
-### Common Errors
-
-#### "Failed to encrypt secret"
-
-**Error:** libsodium encryption error
-
-**Solution:**
-```bash
-# Reinstall dependencies
-rm -rf node_modules
-npm install
-
-# If still failing, try:
-npm install libsodium-wrappers --save
-```
-
-#### "Invalid YAML syntax"
-
-**Error:** When using config files
-
-**Solution:**
-```bash
-# Validate YAML syntax
-npm install -g js-yaml
-js-yaml config.yaml
-
-# Or use online validator: yamllint.com
-
-# Common issues:
-# - Incorrect indentation (use spaces, not tabs)
-# - Missing quotes around special characters
-# - Malformed arrays/objects
-```
-
-#### "Invalid environment name"
-
-**Error:**
-```
-✗ Invalid environment name. Must be lowercase letters, numbers, and hyphens (min 3 chars).
-```
-
-**Rules:**
-- Lowercase letters only
-- Numbers allowed
-- Hyphens allowed (not at start/end)
-- No spaces or special characters
-- Minimum 3 characters
-
-**Valid examples:**
-- `production`
-- `client-abc-staging`
-- `dev-environment-2`
-
-**Invalid examples:**
-- `Production` (uppercase)
-- `My Environment` (spaces)
-- `prod_env` (underscores)
-
-#### "Permission denied writing tokens"
-
-**Error:** Cannot write to ~/.sembix directory
-
-**Solution:**
-```bash
-# Check directory permissions
-ls -la ~/.sembix
-
-# Fix permissions
-chmod 700 ~/.sembix
-chmod 600 ~/.sembix/tokens/*
-
-# If directory doesn't exist
-mkdir -p ~/.sembix/tokens
-chmod 700 ~/.sembix
-```
-
-#### "Invalid input format" (Workflows)
-
-**Error:** Workflow input validation failed
-
-**Solution:**
-```bash
-# Validate JSON syntax
-echo '{"key":"value"}' | jq .
-
-# Use file for complex inputs
-cat inputs.json | jq .  # Validate
-sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs @inputs.json
-
-# Check required vs optional inputs
-sembix workflow template show --project-id proj_123 --workflow-id wf_456
-```
-
-### Configuration Issues
-
-#### Config file not found
-
-**Error:**
-```
-✗ Config file not found: production.yaml
-```
-
-**Solution:**
-```bash
-# Use absolute path
-sembix studio create --config /full/path/to/production.yaml
-
-# Or relative to current directory
-sembix studio create --config ./configs/production.yaml
-
-# Verify file exists
-ls -la production.yaml
-```
-
-#### Config validation failed
-
-**Error:** Config file validation errors
-
-**Solution:**
-1. Check config.example.yaml for correct format
-2. Ensure all required fields are present
-3. Validate data types (strings, booleans, numbers)
-4. Check ARN formats match AWS patterns
-5. Verify CIDR blocks are valid
-
-### Build/Installation Issues
-
-#### "Cannot find module"
-
-**Error:** Module resolution errors
-
-**Solution:**
-```bash
-# Reinstall dependencies
-rm -rf node_modules package-lock.json
-npm install
-
-# Rebuild TypeScript
-npm run build
-
-# If still failing, check Node version
-node --version  # Should be 20 or higher
-```
-
-#### "Command not found: sembix"
-
-**Error:** CLI not in PATH after installation
-
-**Solution:**
-```bash
-# Global install
-npm install -g @sembix/cli
-
-# Verify installation
-which sembix
-sembix --version
-
-# If using npm link (development)
-npm link
-
-# Add npm global bin to PATH if needed
-export PATH="$PATH:$(npm config get prefix)/bin"
-```
-
-### CI/CD Issues
-
-#### Client credentials not working
-
-**Error:** SEMBIX_CLIENT_ID and SEMBIX_CLIENT_SECRET set but authentication fails
-
-**Solution:**
-1. Verify credentials are correct (no extra spaces)
-2. Check client has required scopes:
-   - `sembix-api/projects.read`
-   - `sembix-api/workflows.read`
-   - `sembix-api/workflows.execute`
-3. Test credentials locally:
-```bash
-export SEMBIX_CLIENT_ID="your-client-id"
-export SEMBIX_CLIENT_SECRET="your-client-secret"
-sembix login  # Should show "Client credentials detected..."
-```
-
-#### Environment variables not recognized
-
-**Error:** CI/CD pipeline can't find credentials
-
-**Solution:**
-```bash
-# GitHub Actions: Use secrets
-env:
-  SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
-  SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
-
-# GitLab CI: Use variables
-variables:
-  SEMBIX_CLIENT_ID: ${M2M_CLIENT_ID}
-  SEMBIX_CLIENT_SECRET: ${M2M_CLIENT_SECRET}
-
-# Verify secrets are set in CI/CD settings
-```
-
-### Getting Help
-
-If you encounter an issue not covered here:
-
-1. **Check version:**
-   ```bash
-   sembix --version
-   ```
-
-2. **Enable verbose output:**
-   ```bash
-   sembix studio create --verbose  # If supported
-   ```
-
-3. **Check logs:**
-   - GitHub token permissions
-   - API endpoint reachability
-   - Config file syntax
-
-4. **Common debugging steps:**
-   ```bash
-   # Verify GitHub access
-   sembix studio list
-
-   # Check profile status
-   sembix profile list
-
-   # Test authentication
-   sembix login --profile production
-
-   # Validate config file
-   js-yaml config.yaml
-   ```
-
-5. **Contact support:**
-   - Provide error message
-   - Include CLI version
-   - Share (sanitized) config file if applicable
-
-## Advanced Topics
-
-### Partial Updates
-
-The `update` command supports partial updates - only provide the flags you want to change:
-
-```bash
-# Only update feature flags
-sembix studio update prod --repo acme/deploy \
-  --deploy-studio-memory true \
-  --enable-bff-waf false
-
-# Only update Hub integration
-sembix studio update prod --repo acme/deploy \
-  --hub-consumer-role arn:aws:iam::123456789012:role/NewConsumer
-```
-
-### Config File Inheritance
-
-Create a base config and override specific values:
-
-```bash
-# base.yaml has common settings
-# production.yaml imports and overrides
-
-sembix studio create --config base.yaml --config production.yaml
-# (Note: Multiple --config flags not yet supported, use CLI flags for overrides)
-
-# Current approach:
-sembix studio create --config base.yaml \
-  --env production \
-  --cloudfront-domain studio.prod.acme.com
-```
-
-### Batch Operations
-
-Create multiple environments with a script:
-
-```bash
-#!/bin/bash
-for CLIENT in client-a client-b client-c; do
-  sembix studio create "${CLIENT}-production" \
-    --config base.yaml \
-    --cloudfront-domain "studio.${CLIENT}.example.com" \
-    --aws-account-id "${CLIENT_AWS_ACCOUNTS[$CLIENT]}"
-done
-```
-
-## License
-
-Proprietary - Sembix AI
-
-## Support
+# Support
 
 For issues or questions, contact the Sembix team or open an issue in the repository.
 
-## See Also
-
-For additional detailed documentation, see these files included in the package:
-
-- [QUICKSTART.md](./QUICKSTART.md) - Step-by-step quick start guide with detailed walkthroughs
-- [USAGE-EXAMPLES.md](./USAGE-EXAMPLES.md) - Comprehensive real-world usage examples and patterns
-- [COMMANDS.md](./COMMANDS.md) - Complete command reference with all options and examples
-- [config.example.yaml](./config.example.yaml) - Fully annotated configuration file example
+# See Also
 
-**Note:** After installing the package (`npm install -g @sembix/cli`), these files are available in your global node_modules directory. The README provides comprehensive documentation, but these supplementary files offer additional depth and examples.
+- [config.example.yaml](./config.example.yaml) - Complete YAML configuration reference
+- [CLAUDE.md](./CLAUDE.md) - Development guide for contributors
+- [CI/CD Setup Guide](./docs/CI-CD-SETUP.md) - CI/CD integration examples