# Workspace Switching System (v2.0.5)

## 🚀 Workspace Switching Completed (2025-10-02)

A centralized workspace management system has been implemented, allowing seamless switching between multiple workspaces without manually editing
configuration files. This builds upon the target-based configuration system.

## Key Features

- **Centralized Configuration**: Single `user_config.yaml` file stores all workspace information
- **Simple CLI Commands**: Switch workspaces with a single command
- **Active Workspace Tracking**: Automatic tracking of currently active workspace
- **Workspace Registry**: Maintain list of all known workspaces
- **User Preferences**: Global user settings that apply across all workspaces
- **Automatic Updates**: Last-used timestamps and metadata automatically managed
- **Validation**: Ensures workspaces have required configuration before activation

## Workspace Management Commands

```bash
# List all registered workspaces
provisioning workspace list

# Show currently active workspace
provisioning workspace active

# Switch to another workspace
provisioning workspace activate <name>
provisioning workspace switch <name>     # alias

# Register a new workspace
provisioning workspace register <name> <path> [--activate]

# Remove workspace from registry (does not delete files)
provisioning workspace remove <name> [--force]

# View user preferences
provisioning workspace preferences

# Set user preference
provisioning workspace set-preference <key> <value>

# Get user preference
provisioning workspace get-preference <key>
```

## Central User Configuration

**Location**: `~/Library/Application Support/provisioning/user_config.yaml`

**Structure**:

```yaml
# Active workspace (current workspace in use)
active_workspace: "librecloud"

# Known workspaces (automatically managed)
workspaces:
  - name: "librecloud"
    path: "/Users/Akasha/project-provisioning/workspace_librecloud"
    last_used: "2025-10-06T12:29:43Z"

  - name: "production"
    path: "/opt/workspaces/production"
    last_used: "2025-10-05T10:15:30Z"

# User preferences (global settings)
preferences:
  editor: "vim"
  output_format: "yaml"
  confirm_delete: true
  confirm_deploy: true
  default_log_level: "info"
  preferred_provider: "upcloud"

# Metadata
metadata:
  created: "2025-10-06T12:29:43Z"
  last_updated: "2025-10-06T13:46:16Z"
  version: "1.0.0"
```

## Usage Example

```bash
# Start with workspace librecloud active
$ provisioning workspace active
Active Workspace:
  Name: librecloud
  Path: /Users/Akasha/project-provisioning/workspace_librecloud
  Last used: 2025-10-06T13:46:16Z

# List all workspaces (● indicates active)
$ provisioning workspace list

Registered Workspaces:

  ● librecloud
      Path: /Users/Akasha/project-provisioning/workspace_librecloud
      Last used: 2025-10-06T13:46:16Z

    production
      Path: /opt/workspaces/production
      Last used: 2025-10-05T10:15:30Z

# Switch to production
$ provisioning workspace switch production
✓ Workspace 'production' activated

Current workspace: production
Path: /opt/workspaces/production

ℹ All provisioning commands will now use this workspace

# All subsequent commands use production workspace
$ provisioning server list
$ provisioning taskserv create kubernetes
```

## Integration with Config System

The workspace switching system integrates seamlessly with the configuration system:

1. **Active Workspace Detection**: Config loader reads `active_workspace` from `user_config.yaml`
2. **Workspace Validation**: Ensures workspace has required `config/provisioning.yaml`
3. **Configuration Loading**: Loads workspace-specific configs automatically
4. **Automatic Timestamps**: Updates `last_used` on workspace activation

**Configuration Hierarchy** (Priority: Low → High):

```plaintext
1. Workspace config      workspace/{name}/config/provisioning.yaml
2. Provider configs      workspace/{name}/config/providers/*.toml
3. Platform configs      workspace/{name}/config/platform/*.toml
4. User config           ~/Library/Application Support/provisioning/user_config.yaml
5. Environment variables PROVISIONING_*
```

## Benefits

- ✅ **No Manual Config Editing**: Switch workspaces with single command
- ✅ **Multiple Workspaces**: Manage dev, staging, production simultaneously
- ✅ **User Preferences**: Global settings across all workspaces
- ✅ **Automatic Tracking**: Last-used timestamps, active workspace markers
- ✅ **Safe Operations**: Validation before activation, confirmation prompts
- ✅ **Backward Compatible**: Old `ws_{name}.yaml` files still supported

For more detailed information, see [Workspace Switching Guide](../infrastructure/workspace-switching-guide.md).