# 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 (true/false)\n- `confirm_deploy`: Require confirmation for deployments (true/false)\n- `default_log_level`: Default log level (debug, info, warn, error)\n- `preferred_provider`: Preferred cloud provider (aws, upcloud, local)\n\n### Output Formats\n\nList workspaces in different formats:\n\n```\n# Table format (default)\nprovisioning workspace list\n\n# JSON format\nprovisioning workspace list --format json\n\n# YAML format\nprovisioning workspace list --format yaml\n```\n\n### Quiet Mode\n\nActivate workspace without output messages:\n\n```\nprovisioning workspace activate production --quiet\n```\n\n## Workspace Requirements\n\nFor a workspace to be activated, it must have:\n\n1. **Directory exists**: The workspace directory must exist on the filesystem\n\n2. **Config directory**: Must have a `config/` directory\n\n   ```bash\n\n   workspace_name/\n   └── config/\n       ├── provisioning.yaml  # Required\n       ├── providers/         # Optional\n       ├── platform/          # Optional\n       └── kms.toml           # Optional\n\n```\n\n3. **Main config file**: Must have `config/provisioning.yaml`\n\nIf these requirements are not met, the activation will fail with helpful error messages:\n\n```\n✗ Workspace 'my-project' not found in registry\n💡 Available workspaces:\n   [list of workspaces]\n💡 Register it first with: provisioning workspace register my-project <path>\n```\n\n```\n✗ Workspace is not migrated to new config system\n💡 Missing: /path/to/workspace/config\n💡 Run migration: provisioning workspace migrate my-project\n```\n\n## Migration from Old System\n\nIf you have workspaces using the old context system (`ws_{name}.yaml` files), they still work but you should register them in the new system:\n\n```\n# Register existing workspace\nprovisioning workspace register old-workspace ~/workspaces/old-workspace\n\n# Activate it\nprovisioning workspace activate old-workspace\n```\n\nThe old `ws_{name}.yaml` files are still supported for backward compatibility, but the new centralized system is recommended.\n\n## Best Practices\n\n### 1. **One Active Workspace at a Time**\n\nOnly one workspace can be active at a time. All provisioning commands use the active workspace's configuration.\n\n### 2. **Use Descriptive Names**\n\nUse clear, descriptive names for your workspaces:\n\n```\n# ✅ Good\nprovisioning workspace register production-us-east ~/workspaces/prod-us-east\nprovisioning workspace register dev-local ~/workspaces/dev\n\n# ❌ Avoid\nprovisioning workspace register ws1 ~/workspaces/workspace1\nprovisioning workspace register temp ~/workspaces/t\n```\n\n### 3. **Keep Workspaces Organized**\n\nStore all workspaces in a consistent location:\n\n```\n~/workspaces/\n├── production/\n├── staging/\n├── development/\n└── testing/\n```\n\n### 4. **Regular Cleanup**\n\nRemove workspaces you no longer use:\n\n```\n# List workspaces to see which ones are unused\nprovisioning workspace list\n\n# Remove old workspace\nprovisioning workspace remove old-workspace\n```\n\n### 5. **Backup User Config**\n\nPeriodically backup your user configuration:\n\n```\ncp "~/Library/Application Support/provisioning/user_config.yaml" \\n   "~/Library/Application Support/provisioning/user_config.yaml.backup"\n```\n\n## Troubleshooting\n\n### Workspace Not Found\n\n**Problem**: `✗ Workspace 'name' not found in registry`\n\n**Solution**: Register the workspace first:\n\n```\nprovisioning workspace register name /path/to/workspace\n```\n\n### Missing Configuration\n\n**Problem**: `✗ Missing workspace configuration`\n\n**Solution**: Ensure the workspace has a `config/provisioning.yaml` file. Run migration if needed:\n\n```\nprovisioning workspace migrate name\n```\n\n### Directory Not Found\n\n**Problem**: `✗ Workspace directory not found: /path/to/workspace`\n\n**Solution**:\n\n1. Check if the workspace was moved or deleted\n2. Update the path or remove from registry:\n\n```\nprovisioning workspace remove name\nprovisioning workspace register name /new/path\n```\n\n### Corrupted User Config\n\n**Problem**: `Error: Failed to parse user config`\n\n**Solution**: The system automatically creates a backup and regenerates the config. Check:\n\n```\nls -la "~/Library/Application Support/provisioning/user_config.yaml"*\n```\n\nRestore from backup if needed:\n\n```\ncp "~/Library/Application Support/provisioning/user_config.yaml.backup.TIMESTAMP" \\n   "~/Library/Application Support/provisioning/user_config.yaml"\n```\n\n## CLI Commands Reference\n\n| Command | Alias | Description |\n| --------- | ------- | ------------- |\n| `provisioning workspace activate <name>` | - | Activate a workspace |\n| `provisioning workspace switch <name>` | - | Alias for activate |\n| `provisioning workspace list` | - | List all registered workspaces |\n| `provisioning workspace active` | - | Show currently active workspace |\n| `provisioning workspace register <name> <path>` | - | Register a new workspace |\n| `provisioning workspace remove <name>` | - | Remove workspace from registry |\n| `provisioning workspace preferences` | - | Show user preferences |\n| `provisioning workspace set-preference <key> <value>` | - | Set a preference |\n| `provisioning workspace get-preference <key>` | - | Get a preference value |\n\n## Integration with Config System\n\nThe workspace switching system is fully integrated with the new target-based configuration system:\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 context          ~/Library/Application Support/provisioning/ws_{name}.yaml (legacy)\n5. User config           ~/Library/Application Support/provisioning/user_config.yaml (new)\n6. Environment variables PROVISIONING_*\n```\n\n### Example Workflow\n\n```\n# 1. Create and activate development workspace\nprovisioning workspace register dev ~/workspaces/dev --activate\n\n# 2. Work on development\nprovisioning server create web-dev-01\nprovisioning taskserv create kubernetes\n\n# 3. Switch to production\nprovisioning workspace switch production\n\n# 4. Deploy to production\nprovisioning server create web-prod-01\nprovisioning taskserv create kubernetes\n\n# 5. Switch back to development\nprovisioning workspace switch dev\n\n# All commands now use dev workspace config\n```\n\n## Nickel Workspace Configuration\n\nStarting with v3.7.0, workspaces use **Nickel** for type-safe, schema-validated configurations.\n\n### Nickel Configuration Features\n\n**Nickel Configuration** (Type-Safe):\n\n```\n{\n  workspace = {\n    name = "myworkspace",\n    version = "1.0.0",\n  },\n  paths = {\n    base = "/path/to/workspace",\n    infra = "/path/to/workspace/infra",\n    config = "/path/to/workspace/config",\n  },\n}\n```\n\n### Benefits of Nickel Configuration\n\n- ✅ **Type Safety**: Catch configuration errors at load time, not runtime\n- ✅ **Schema Validation**: Required fields, value constraints, format checking\n- ✅ **Lazy Evaluation**: Only computes what's needed\n- ✅ **Self-Documenting**: Records provide instant documentation\n- ✅ **Merging**: Powerful record merging for composition\n\n### Viewing Workspace Configuration\n\n```\n# View your Nickel workspace configuration\nprovisioning workspace config show\n\n# View in different formats\nprovisioning workspace config show --format=yaml    # YAML output\nprovisioning workspace config show --format=json    # JSON output\nprovisioning workspace config show --format=nickel  # Raw Nickel file\n\n# Validate configuration\nprovisioning workspace config validate\n# Output: ✅ Validation complete - all configs are valid\n\n# Show configuration hierarchy\nprovisioning workspace config hierarchy\n```\n\n## See Also\n\n- **Configuration Guide**: `docs/architecture/adr/ADR-010-configuration-format-strategy.md`\n- **Migration Guide**: [Nickel Migration](../architecture/adr/adr-011-nickel-migration.md)\n- **From-Scratch Guide**: [From-Scratch Guide](../guides/from-scratch.md)\n- **Nickel Patterns**: Nickel Language Module System\n\n---\n\n**Maintained By**: Infrastructure Team\n**Version**: 2.0.0 (Updated for Nickel)\n**Status**: ✅ Production Ready\n**Last Updated**: 2025-12-03