# Workspace Generation - Quick Reference\n\n**Updated for Nickel-based workspaces with auto-generated documentation**\n\n## Quick Start: Create a Workspace\n\n```\n# Interactive mode (recommended)\nprovisioning workspace init\n\n# Non-interactive mode with explicit path\nprovisioning workspace init my_workspace /path/to/my_workspace\n\n# With activation\nprovisioning workspace init my_workspace /path/to/my_workspace --activate\n```\n\n## What Gets Created Automatically\n\nWhen you run `provisioning workspace init`, the system creates:\n\n```\nmy_workspace/\n├── config/\n│   ├── config.ncl           # Master Nickel configuration\n│   ├── providers/           # Provider configurations\n│   └── platform/            # Platform service configs\n│\n├── infra/\n│   └── default/\n│       ├── main.ncl         # Infrastructure definition\n│       └── servers.ncl      # Server configurations\n│\n├── docs/                    # ✨ AUTO-GENERATED GUIDES\n│   ├── README.md           # Workspace overview\n│   ├── deployment-guide.md # Step-by-step deployment\n│   ├── configuration-guide.md # Configuration reference\n│   └── troubleshooting.md  # Common issues & solutions\n│\n├── .providers/\n├── .kms/\n├── .provisioning/\n└── workspace.nu            # Utility scripts\n```\n\n## Key Files Created\n\n### Master Configuration: `config/config.ncl`\n\n```\n{\n  workspace = {\n    name = "my_workspace",\n    path = "/path/to/my_workspace",\n    description = "Workspace: my_workspace",\n    metadata = {\n      owner = "your_username",\n      created = "2025-01-07T19:30:00Z",\n      environment = "development",\n    },\n  },\n\n  providers = {\n    local = {\n      name = "local",\n      enabled = true,\n      workspace = "my_workspace",\n      auth = { interface = "local" },\n      paths = {\n        base = ".providers/local",\n        cache = ".providers/local/cache",\n        state = ".providers/local/state",\n      },\n    },\n  },\n}\n```\n\n### Infrastructure: `infra/default/main.ncl`\n\n```\n{\n  workspace_name = "my_workspace",\n  infrastructure = "default",\n  servers = [\n    {\n      hostname = "my-workspace-server-0",\n      provider = "local",\n      plan = "1xCPU-2 GB",\n      zone = "local",\n      storages = [{total = 25}],\n    },\n  ],\n}\n```\n\n## Auto-Generated Guides\n\nEvery workspace includes 4 auto-generated guides in the `docs/` directory:\n\n| Guide | Content |\n| ------- | --------- |\n| **README.md** | Workspace overview, quick start, and structure |\n| **deployment-guide.md** | Step-by-step deployment for your infrastructure |\n| **configuration-guide.md** | Configuration options specific to your setup |\n| **troubleshooting.md** | Solutions for common issues |\n\nThese guides are customized for your workspace's:\n- Configured providers\n- Infrastructure definitions\n- Server configurations\n- Platform services\n\n## Initialization Process (8 Steps)\n\n```\nSTEP 1: Create directory structure\n        └─ workspace/, config/, infra/default/, etc.\n\nSTEP 2: Generate Nickel configuration\n        ├─ config/config.ncl (master config)\n        └─ infra/default/*.ncl (infrastructure files)\n\nSTEP 3: Configure providers\n        └─ Setup local provider (default)\n\nSTEP 4: Initialize metadata\n        └─ .provisioning/metadata.yaml\n\nSTEP 5: Activate workspace (if requested)\n        └─ Set as default workspace\n\nSTEP 6: Create .gitignore\n        └─ Workspace-specific ignore rules\n\nSTEP 7: ✨ GENERATE DOCUMENTATION\n        ├─ Extract workspace metadata\n        ├─ Render 4 workspace guides\n        └─ Place in docs/ directory\n\nSTEP 8: Display summary\n        └─ Show workspace path and documentation location\n```\n\n## Common Commands\n\n### Workspace Management\n\n```\n# Create interactive workspace\nprovisioning workspace init\n\n# Create with explicit path and activate\nprovisioning workspace init my_workspace /path/to/workspace --activate\n\n# List all workspaces\nprovisioning workspace list\n\n# Activate workspace\nprovisioning workspace activate my_workspace\n\n# Show active workspace\nprovisioning workspace active\n```\n\n### Configuration\n\n```\n# Validate Nickel configuration\nnickel typecheck config/config.ncl\nnickel typecheck infra/default/main.ncl\n\n# Validate with provisioning system\nprovisioning validate config\n```\n\n### Deployment\n\n```\n# Dry-run (check mode)\nprovisioning -c server create\n\n# Actual deployment\nprovisioning server create\n\n# List servers\nprovisioning server list\n```\n\n## Workspace Directory Structure\n\n### Auto-Generated Structure\n\n```\nmy_workspace/\n├── config/\n│   ├── config.ncl                 # Master configuration\n│   ├── providers/                 # Provider configs\n│   └── platform/                  # Platform configs\n│\n├── infra/\n│   └── default/\n│       ├── main.ncl              # Infrastructure definition\n│       └── servers.ncl           # Server definitions\n│\n├── docs/                         # AUTO-GENERATED GUIDES\n│   ├── README.md                # Workspace overview\n│   ├── deployment-guide.md      # Step-by-step deployment\n│   ├── configuration-guide.md   # Configuration reference\n│   └── troubleshooting.md       # Common issues & solutions\n│\n├── .providers/                   # Provider state & cache\n├── .kms/                        # KMS data\n├── .provisioning/               # Workspace metadata\n└── workspace.nu                 # Utility scripts\n```\n\n## Customization Guide\n\n### Edit Configuration\n\n```\n# Master workspace configuration\nvim config/config.ncl\n\n# Infrastructure definition\nvim infra/default/main.ncl\n\n# Server definitions\nvim infra/default/servers.ncl\n```\n\n### Add Multiple Infrastructures\n\n```\n# Create new infrastructure environment\nmkdir -p infra/production infra/staging\n\n# Copy template files\ncp infra/default/main.ncl infra/production/main.ncl\ncp infra/default/servers.ncl infra/production/servers.ncl\n\n# Edit for your needs\nvim infra/production/servers.ncl\n```\n\n### Configure Providers\n\nUpdate `config/config.ncl` to enable cloud providers:\n\n```\nproviders = {\n  upcloud = {\n    name = "upcloud",\n    enabled = true,              # Set to true\n    workspace = "my_workspace",\n    auth = { interface = "API" },\n    paths = {\n      base = ".providers/upcloud",\n      cache = ".providers/upcloud/cache",\n      state = ".providers/upcloud/state",\n    },\n    api = {\n      url = "https://api.upcloud.com/1.3",\n      timeout = 30,\n    },\n  },\n}\n```\n\n## Next Steps\n\n1. **Read auto-generated guides** in `docs/`\n2. **Customize configuration** in Nickel files\n3. **Validate with**: `nickel typecheck config/config.ncl`\n4. **Test deployment** with dry-run mode: `provisioning -c server create`\n5. **Deploy infrastructure** when ready\n\n## Documentation References\n\n- **[Workspace Setup Guide](workspace-setup.md)** - Complete setup instructions\n- **[Workspace Switching Guide](workspace-switching-guide.md)** - Managing multiple workspaces\n- **[Infrastructure Guide](../infrastructure/infrastructure-management.md)** - Infrastructure details
