# Workspace Switching Guide\n\n**Version**: 1.0.0\n**Date**: 2025-10-06\n**Status**: ✅ Production Ready\n\n## Overview\n\nThe provisioning system now includes a centralized workspace management system that allows you to easily switch between multiple workspaces without\nmanually editing configuration files.\n\n## Quick Start\n\n### List Available Workspaces\n\n```\nprovisioning workspace list\n```\n\nOutput:\n\n```\nRegistered Workspaces:\n\n ● librecloud\n Path: /Users/Akasha/project-provisioning/workspace_librecloud\n Last used: 2025-10-06T12:29:43Z\n\n production\n Path: /opt/workspaces/production\n Last used: 2025-10-05T10:15:30Z\n```\n\nThe green ● indicates the currently active workspace.\n\n### Check Active Workspace\n\n```\nprovisioning workspace active\n```\n\nOutput:\n\n```\nActive Workspace:\n Name: librecloud\n Path: /Users/Akasha/project-provisioning/workspace_librecloud\n Last used: 2025-10-06T12:29:43Z\n```\n\n### Switch to Another Workspace\n\n```\n# Option 1: Using activate\nprovisioning workspace activate production\n\n# Option 2: Using switch (alias)\nprovisioning workspace switch production\n```\n\nOutput:\n\n```\n✓ Workspace 'production' activated\n\nCurrent workspace: production\nPath: /opt/workspaces/production\n\nℹ All provisioning commands will now use this workspace\n```\n\n### Register a New Workspace\n\n```\n# Register without activating\nprovisioning workspace register my-project ~/workspaces/my-project\n\n# Register and activate immediately\nprovisioning workspace register my-project ~/workspaces/my-project --activate\n```\n\n### Remove Workspace from Registry\n\n```\n# With confirmation prompt\nprovisioning workspace remove old-workspace\n\n# Skip confirmation\nprovisioning workspace remove old-workspace --force\n```\n\n**Note**: This only removes the workspace from the registry. The workspace files are NOT deleted.\n\n## Architecture\n\n### Central User Configuration\n\nAll workspace information is stored in a central user configuration file:\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### How It Works\n\n1. **Workspace Registration**: When you register a workspace, it's added to the `workspaces` list in `user_config.yaml`\n\n2. **Activation**: When you activate a workspace:\n - `active_workspace` is updated to the workspace name\n - The workspace's `last_used` timestamp is updated\n - All provisioning commands now use this workspace's configuration\n\n3. **Configuration Loading**: The config loader reads `active_workspace` from `user_config.yaml` and loads:\n - `workspace_path/config/provisioning.yaml`\n - `workspace_path/config/providers/*.toml`\n - `workspace_path/config/platform/*.toml`\n - `workspace_path/config/kms.toml`\n\n## Advanced Features\n\n### User Preferences\n\nYou can set global user preferences that apply across all workspaces:\n\n```\n# Get a preference value\nprovisioning workspace get-preference editor\n\n# Set a preference value\nprovisioning workspace set-preference editor "code"\n\n# View all preferences\nprovisioning workspace preferences\n```\n\n**Available Preferences**:\n\n- `editor`: Default editor for config files (vim, code, nano, etc.)\n- `output_format`: Default output format (yaml, json, toml)\n- `confirm_delete`: Require confirmation for deletions (t
