# Workspace Switching System (v2.0.5)\n\n## 🚀 Workspace Switching Completed (2025-10-02)\n\nA centralized workspace management system has been implemented, allowing seamless switching between multiple workspaces without manually editing\nconfiguration files. This builds upon the target-based configuration system.\n\n## Key Features\n\n- **Centralized Configuration**: Single `user_config.yaml` file stores all workspace information\n- **Simple CLI Commands**: Switch workspaces with a single command\n- **Active Workspace Tracking**: Automatic tracking of currently active workspace\n- **Workspace Registry**: Maintain list of all known workspaces\n- **User Preferences**: Global user settings that apply across all workspaces\n- **Automatic Updates**: Last-used timestamps and metadata automatically managed\n- **Validation**: Ensures workspaces have required configuration before activation\n\n## Workspace Management Commands\n\n```\n# List all registered workspaces\nprovisioning workspace list\n\n# Show currently active workspace\nprovisioning workspace active\n\n# Switch to another workspace\nprovisioning workspace activate <name>\nprovisioning workspace switch <name>     # alias\n\n# Register a new workspace\nprovisioning workspace register <name> <path> [--activate]\n\n# Remove workspace from registry (does not delete files)\nprovisioning workspace remove <name> [--force]\n\n# View user preferences\nprovisioning workspace preferences\n\n# Set user preference\nprovisioning workspace set-preference <key> <value>\n\n# Get user preference\nprovisioning workspace get-preference <key>\n```\n\n## Central User Configuration\n\n**Location**: `~/Library/Application Support/provisioning/user_config.yaml`\n\n**Structure**:\n\n```\n# Active workspace (current workspace in use)\nactive_workspace: "librecloud"\n\n# Known workspaces (automatically managed)\nworkspaces:\n  - name: "librecloud"\n    path: "/Users/Akasha/project-provisioning/workspace_librecloud"\n    last_used: "2025-10-06T12:29:43Z"\n\n  - name: "production"\n    path: "/opt/workspaces/production"\n    last_used: "2025-10-05T10:15:30Z"\n\n# User preferences (global settings)\npreferences:\n  editor: "vim"\n  output_format: "yaml"\n  confirm_delete: true\n  confirm_deploy: true\n  default_log_level: "info"\n  preferred_provider: "upcloud"\n\n# Metadata\nmetadata:\n  created: "2025-10-06T12:29:43Z"\n  last_updated: "2025-10-06T13:46:16Z"\n  version: "1.0.0"\n```\n\n## Usage Example\n\n```\n# Start with workspace librecloud active\n$ provisioning workspace active\nActive Workspace:\n  Name: librecloud\n  Path: /Users/Akasha/project-provisioning/workspace_librecloud\n  Last used: 2025-10-06T13:46:16Z\n\n# List all workspaces (● indicates active)\n$ provisioning workspace list\n\nRegistered Workspaces:\n\n  ● librecloud\n      Path: /Users/Akasha/project-provisioning/workspace_librecloud\n      Last used: 2025-10-06T13:46:16Z\n\n    production\n      Path: /opt/workspaces/production\n      Last used: 2025-10-05T10:15:30Z\n\n# Switch to production\n$ provisioning workspace switch production\n✓ Workspace 'production' activated\n\nCurrent workspace: production\nPath: /opt/workspaces/production\n\nℹ All provisioning commands will now use this workspace\n\n# All subsequent commands use production workspace\n$ provisioning server list\n$ provisioning taskserv create kubernetes\n```\n\n## Integration with Config System\n\nThe workspace switching system integrates seamlessly with the configuration system:\n\n1. **Active Workspace Detection**: Config loader reads `active_workspace` from `user_config.yaml`\n2. **Workspace Validation**: Ensures workspace has required `config/provisioning.yaml`\n3. **Configuration Loading**: Loads workspace-specific configs automatically\n4. **Automatic Timestamps**: Updates `last_used` on workspace activation\n\n**Configuration Hierarchy** (Priority: Low → High):\n\n```\n1. Workspace config      workspace/{name}/config/provisioning.yaml\n2. Provider configs      workspace/{name}/config/providers/*.toml\n3. Platform configs      workspace/{name}/config/platform/*.toml\n4. User config           ~/Library/Application Support/provisioning/user_config.yaml\n5. Environment variables PROVISIONING_*\n```\n\n## Benefits\n\n- ✅ **No Manual Config Editing**: Switch workspaces with single command\n- ✅ **Multiple Workspaces**: Manage dev, staging, production simultaneously\n- ✅ **User Preferences**: Global settings across all workspaces\n- ✅ **Automatic Tracking**: Last-used timestamps, active workspace markers\n- ✅ **Safe Operations**: Validation before activation, confirmation prompts\n- ✅ **Backward Compatible**: Old `ws_{name}.yaml` files still supported\n\nFor more detailed information, see [Workspace Switching Guide](../infrastructure/workspace-switching-guide.md).