# Unified Workspace:Infrastructure Reference System\n\n**Version**: 1.0.0\n**Last Updated**: 2025-12-04\n\n## Overview\n\nThe Workspace:Infrastructure Reference System provides a unified notation for managing workspaces and their associated infrastructure. This system\neliminates the need to specify infrastructure separately and enables convenient defaults.\n\n## Quick Start\n\n### Temporal Override (Single Command)\n\nUse the `-ws` flag with `workspace:infra` notation:\n\n```\n# Use production workspace with sgoyol infrastructure for this command only\nprovisioning server list -ws production:sgoyol\n\n# Use default infrastructure of active workspace\nprovisioning taskserv create kubernetes\n```\n\n### Persistent Activation\n\nActivate a workspace with a default infrastructure:\n\n```\n# Activate librecloud workspace and set wuji as default infra\nprovisioning workspace activate librecloud:wuji\n\n# Now all commands use librecloud:wuji by default\nprovisioning server list\n```\n\n## Notation Syntax\n\n### Basic Format\n\n```\nworkspace:infra\n```\n\n| Part | Description | Example |\n| ------ | ------------- | --------- |\n| `workspace` | Workspace name | `librecloud` |\n| `:` | Separator | - |\n| `infra` | Infrastructure name | `wuji` |\n\n### Examples\n\n| Notation | Workspace | Infrastructure |\n| ---------- | ----------- | ----------------- |\n| `librecloud:wuji` | librecloud | wuji |\n| `production:sgoyol` | production | sgoyol |\n| `dev:local` | dev | local |\n| `librecloud` | librecloud | (from default or context) |\n\n## Resolution Priority\n\nWhen no infrastructure is explicitly specified, the system uses this priority order:\n\n1. **Explicit `--infra` flag** (highest)\n\n   ```bash\n   provisioning server list --infra another-infra\n   ```\n\n1. **PWD Detection**\n\n   ```bash\n   cd workspace_librecloud/infra/wuji\n   provisioning server list  # Auto-detects wuji\n   ```\n\n2. **Default Infrastructure**\n\n   ```bash\n   # If workspace has default_infra set\n   provisioning server list  # Uses configured default\n   ```\n\n3. **Error** (no infra found)\n\n   ```bash\n   # Error: No infrastructure specified\n   ```\n\n## Usage Patterns\n\n### Pattern 1: Temporal Override for Commands\n\nUse `-ws` to override workspace:infra for a single command:\n\n```\n# Currently in librecloud:wuji context\nprovisioning server list  # Shows librecloud:wuji\n\n# Temporary override for this command only\nprovisioning server list -ws production:sgoyol  # Shows production:sgoyol\n\n# Back to original context\nprovisioning server list  # Shows librecloud:wuji again\n```\n\n### Pattern 2: Persistent Workspace Activation\n\nSet a workspace as active with a default infrastructure:\n\n```\n# List available workspaces\nprovisioning workspace list\n\n# Activate with infra notation\nprovisioning workspace activate production:sgoyol\n\n# All subsequent commands use production:sgoyol\nprovisioning server list\nprovisioning taskserv create kubernetes\n```\n\n### Pattern 3: PWD-Based Inference\n\nThe system auto-detects workspace and infrastructure from your current directory:\n\n```\n# Your workspace structure\nworkspace_librecloud/\n  infra/\n    wuji/\n      settings.ncl\n    another/\n      settings.ncl\n\n# Navigation auto-detects context\ncd workspace_librecloud/infra/wuji\nprovisioning server list  # Uses wuji automatically\n\ncd ../another\nprovisioning server list  # Switches to another\n```\n\n### Pattern 4: Default Infrastructure Management\n\nSet a workspace-specific default infrastructure:\n\n```\n# During activation\nprovisioning workspace activate librecloud:wuji\n\n# Or explicitly after activation\nprovisioning workspace set-default-infra librecloud another-infra\n\n# View current defaults\nprovisioning workspace list\n```\n\n## Command Reference\n\n### Workspace Commands\n\n```\n# Activate workspace with infra\nprovisioning workspace activate workspace:infra\n\n# Switch to different workspace\nprovisioning workspace switch workspace_name\n\n# List all workspaces\nprovisioning workspace list\n\n# Show active workspace\nprovisioning workspace active\n\n# Set default infrastructure\nprovisioning workspace set-default-infra workspace_name infra_name\n\n# Get default infrastructure\nprovisioning workspace get-default-infra workspace_name\n```\n\n### Common Commands with `-ws`\n\n```\n# Server operations\nprovisioning server create -ws workspace:infra\nprovisioning server list -ws workspace:infra\nprovisioning server delete name -ws workspace:infra\n\n# Task service operations\nprovisioning taskserv create kubernetes -ws workspace:infra\nprovisioning taskserv delete kubernetes -ws workspace:infra\n\n# Infrastructure operations\nprovisioning infra validate -ws workspace:infra\nprovisioning infra list -ws workspace:infra\n```\n\n## Features\n\n### ✅ Unified Notation\n\n- Single `workspace:infra` format for all references\n- Works with all provisioning commands\n- Backward compatible with existing workflows\n\n### ✅ Temporal Override\n\n- Use `-ws` flag for single-command overrides\n- No permanent state changes\n- Automatically reverted after command\n\n### ✅ Persistent Defaults\n\n- Set default infrastructure per workspace\n- Eliminates repetitive `--infra` flags\n- Survives across sessions\n\n### ✅ Smart Detection\n\n- Auto-detects workspace from directory\n- Auto-detects infrastructure from PWD\n- Fallback to configured defaults\n\n### ✅ Error Handling\n\n- Clear error messages when infra not found\n- Validation of workspace and infra existence\n- Helpful hints for missing configurations\n\n## Environment Context\n\n### TEMP_WORKSPACE Variable\n\nThe system uses `$env.TEMP_WORKSPACE` for temporal overrides:\n\n```\n# Set temporarily (via -ws flag automatically)\n$env.TEMP_WORKSPACE = "production"\n\n# Check current context\necho $env.TEMP_WORKSPACE\n\n# Clear after use\nhide-env TEMP_WORKSPACE\n```\n\n## Validation\n\n### Validating Notation\n\n```\n# Valid notation formats\nlibrecloud:wuji           # Standard format\nproduction:sgoyol.v2      # With dots and hyphens\ndev-01:local-test         # Multiple hyphens\nprod123:infra456          # Numeric names\n\n# Special characters\nlib-cloud_01:wu-ji.v2    # Mix of all allowed chars\n```\n\n### Error Cases\n\n```\n# Workspace not found\nprovisioning workspace activate unknown:infra\n# Error: Workspace 'unknown' not found in registry\n\n# Infrastructure not found\nprovisioning workspace activate librecloud:unknown\n# Error: Infrastructure 'unknown' not found in workspace 'librecloud'\n\n# Empty specification\nprovisioning workspace activate ""\n# Error: Workspace '' not found in registry\n```\n\n## Configuration\n\n### User Configuration\n\nDefault infrastructure is stored in `~/Library/Application Support/provisioning/user_config.yaml`:\n\n```\nactive_workspace: "librecloud"\n\nworkspaces:\n  - name: "librecloud"\n    path: "/Users/you/workspaces/librecloud"\n    last_used: "2025-12-04T12:00:00Z"\n    default_infra: "wuji"  # Default infrastructure\n\n  - name: "production"\n    path: "/opt/workspaces/production"\n    last_used: "2025-12-03T15:30:00Z"\n    default_infra: "sgoyol"\n```\n\n### Workspace Schema\n\nIn `provisioning/schemas/workspace_config.ncl`:\n\n```\n{\n  InfraConfig = {\n    current | String,  # Infrastructure context settings\n    default | String | optional,  # Default infrastructure for workspace\n  },\n}\n```\n\n## Best Practices\n\n### 1. Use Persistent Activation for Long Sessions\n\n```\n# Good: Activate at start of session\nprovisioning workspace activate production:sgoyol\n\n# Then use simple commands\nprovisioning server list\nprovisioning taskserv create kubernetes\n```\n\n### 2. Use Temporal Override for Ad-Hoc Operations\n\n```\n# Good: Quick one-off operation\nprovisioning server list -ws production:other-infra\n\n# Avoid: Repeated -ws flags\nprovisioning server list -ws prod:infra1\nprovisioning taskserv list -ws prod:infra1  # Better to activate once\n```\n\n### 3. Navigate with PWD for Context Awareness\n\n```\n# Good: Navigate to infrastructure directory\ncd workspace_librecloud/infra/wuji\nprovisioning server list  # Auto-detects context\n\n# Works well with: cd - history, terminal multiplexer panes\n```\n\n### 4. Set Meaningful Defaults\n\n```\n# Good: Default to production infrastructure\nprovisioning workspace activate production:main-infra\n\n# Avoid: Default to dev infrastructure in production workspace\n```\n\n## Troubleshooting\n\n### Issue: "Workspace not found in registry"\n\n**Solution**: Register the workspace first\n\n```\nprovisioning workspace register librecloud /path/to/workspace_librecloud\n```\n\n### Issue: "Infrastructure not found"\n\n**Solution**: Verify infrastructure directory exists\n\n```\nls workspace_librecloud/infra/  # Check available infras\nprovisioning workspace activate librecloud:wuji  # Use correct name\n```\n\n### Issue: Temporal override not working\n\n**Solution**: Ensure you're using `-ws` flag correctly\n\n```\n# Correct\nprovisioning server list -ws production:sgoyol\n\n# Incorrect (missing space)\nprovisioning server list-wsproduction:sgoyol\n\n# Incorrect (ws is not a command)\nprovisioning -ws production:sgoyol server list\n```\n\n### Issue: PWD detection not working\n\n**Solution**: Navigate to proper infrastructure directory\n\n```\n# Must be in workspace structure\ncd workspace_name/infra/infra_name\n\n# Then run command\nprovisioning server list\n```\n\n## Migration from Old System\n\n### Old Way\n\n```\nprovisioning workspace activate librecloud\nprovisioning --infra wuji server list\nprovisioning --infra wuji taskserv create kubernetes\n```\n\n### New Way\n\n```\nprovisioning workspace activate librecloud:wuji\nprovisioning server list\nprovisioning taskserv create kubernetes\n```\n\n## Performance Notes\n\n- **Notation parsing**: <1 ms per command\n- **Workspace detection**: <5 ms from PWD\n- **Workspace switching**: ~100 ms (includes platform activation)\n- **Temporal override**: No additional overhead\n\n## Backward Compatibility\n\nAll existing commands and flags continue to work:\n\n```\n# Old syntax still works\nprovisioning --infra wuji server list\n\n# New syntax also works\nprovisioning server list -ws librecloud:wuji\n\n# Mix and match\nprovisioning --infra other-infra server list -ws librecloud:wuji\n# Uses other-infra (explicit flag takes priority)\n```\n\n## See Also\n\n- `provisioning help workspace` - Workspace commands\n- `provisioning help infra` - Infrastructure commands\n- `docs/architecture/ARCHITECTURE_OVERVIEW.md` - Overall architecture\n- `docs/user/WORKSPACE_SWITCHING_GUIDE.md` - Workspace switching details
