provisioning/docs/src/guides/workspace-generation-quick-reference.md

# Workspace Generation - Quick Reference

**Updated for Nickel-based workspaces with auto-generated documentation**

## Quick Start: Create a Workspace

```bash
# Interactive mode (recommended)
provisioning workspace init

# Non-interactive mode with explicit path
provisioning workspace init my_workspace /path/to/my_workspace

# With activation
provisioning workspace init my_workspace /path/to/my_workspace --activate
```

## What Gets Created Automatically

When you run `provisioning workspace init`, the system creates:

```text
my_workspace/
├── config/
│   ├── config.ncl           # Master Nickel configuration
│   ├── providers/           # Provider configurations
│   └── platform/            # Platform service configs
│
├── infra/
│   └── default/
│       ├── main.ncl         # Infrastructure definition
│       └── servers.ncl      # Server configurations
│
├── docs/                    # ✨ AUTO-GENERATED GUIDES
│   ├── README.md           # Workspace overview
│   ├── deployment-guide.md # Step-by-step deployment
│   ├── configuration-guide.md # Configuration reference
│   └── troubleshooting.md  # Common issues & solutions
│
├── .providers/
├── .kms/
├── .provisioning/
└── workspace.nu            # Utility scripts
```

## Key Files Created

### Master Configuration: `config/config.ncl`

```nickel
{
  workspace = {
    name = "my_workspace",
    path = "/path/to/my_workspace",
    description = "Workspace: my_workspace",
    metadata = {
      owner = "your_username",
      created = "2025-01-07T19:30:00Z",
      environment = "development",
    },
  },

  providers = {
    local = {
      name = "local",
      enabled = true,
      workspace = "my_workspace",
      auth = { interface = "local" },
      paths = {
        base = ".providers/local",
        cache = ".providers/local/cache",
        state = ".providers/local/state",
      },
    },
  },
}
```

### Infrastructure: `infra/default/main.ncl`

```nickel
{
  workspace_name = "my_workspace",
  infrastructure = "default",
  servers = [
    {
      hostname = "my-workspace-server-0",
      provider = "local",
      plan = "1xCPU-2 GB",
      zone = "local",
      storages = [{total = 25}],
    },
  ],
}
```

## Auto-Generated Guides

Every workspace includes 4 auto-generated guides in the `docs/` directory:

| Guide | Content |
|-------|---------|
| **README.md** | Workspace overview, quick start, and structure |
| **deployment-guide.md** | Step-by-step deployment for your infrastructure |
| **configuration-guide.md** | Configuration options specific to your setup |
| **troubleshooting.md** | Solutions for common issues |

These guides are customized for your workspace's:
- Configured providers
- Infrastructure definitions
- Server configurations
- Platform services

## Initialization Process (8 Steps)

```plaintext
STEP 1: Create directory structure
        └─ workspace/, config/, infra/default/, etc.

STEP 2: Generate Nickel configuration
        ├─ config/config.ncl (master config)
        └─ infra/default/*.ncl (infrastructure files)

STEP 3: Configure providers
        └─ Setup local provider (default)

STEP 4: Initialize metadata
        └─ .provisioning/metadata.yaml

STEP 5: Activate workspace (if requested)
        └─ Set as default workspace

STEP 6: Create .gitignore
        └─ Workspace-specific ignore rules

STEP 7: ✨ GENERATE DOCUMENTATION
        ├─ Extract workspace metadata
        ├─ Render 4 workspace guides
        └─ Place in docs/ directory

STEP 8: Display summary
        └─ Show workspace path and documentation location
```

## Common Commands

### Workspace Management

```bash
# Create interactive workspace
provisioning workspace init

# Create with explicit path and activate
provisioning workspace init my_workspace /path/to/workspace --activate

# List all workspaces
provisioning workspace list

# Activate workspace
provisioning workspace activate my_workspace

# Show active workspace
provisioning workspace active
```

### Configuration

```bash
# Validate Nickel configuration
nickel typecheck config/config.ncl
nickel typecheck infra/default/main.ncl

# Validate with provisioning system
provisioning validate config
```

### Deployment

```bash
# Dry-run (check mode)
provisioning -c server create

# Actual deployment
provisioning server create

# List servers
provisioning server list
```

## Workspace Directory Structure

### Auto-Generated Structure

```bash
my_workspace/
├── config/
│   ├── config.ncl                 # Master configuration
│   ├── providers/                 # Provider configs
│   └── platform/                  # Platform configs
│
├── infra/
│   └── default/
│       ├── main.ncl              # Infrastructure definition
│       └── servers.ncl           # Server definitions
│
├── docs/                         # AUTO-GENERATED GUIDES
│   ├── README.md                # Workspace overview
│   ├── deployment-guide.md      # Step-by-step deployment
│   ├── configuration-guide.md   # Configuration reference
│   └── troubleshooting.md       # Common issues & solutions
│
├── .providers/                   # Provider state & cache
├── .kms/                        # KMS data
├── .provisioning/               # Workspace metadata
└── workspace.nu                 # Utility scripts
```

## Customization Guide

### Edit Configuration

```bash
# Master workspace configuration
vim config/config.ncl

# Infrastructure definition
vim infra/default/main.ncl

# Server definitions
vim infra/default/servers.ncl
```

### Add Multiple Infrastructures

```bash
# Create new infrastructure environment
mkdir -p infra/production infra/staging

# Copy template files
cp infra/default/main.ncl infra/production/main.ncl
cp infra/default/servers.ncl infra/production/servers.ncl

# Edit for your needs
vim infra/production/servers.ncl
```

### Configure Providers

Update `config/config.ncl` to enable cloud providers:

```nickel
providers = {
  upcloud = {
    name = "upcloud",
    enabled = true,              # Set to true
    workspace = "my_workspace",
    auth = { interface = "API" },
    paths = {
      base = ".providers/upcloud",
      cache = ".providers/upcloud/cache",
      state = ".providers/upcloud/state",
    },
    api = {
      url = "https://api.upcloud.com/1.3",
      timeout = 30,
    },
  },
}
```

## Next Steps

1. **Read auto-generated guides** in `docs/`
2. **Customize configuration** in Nickel files
3. **Validate with**: `nickel typecheck config/config.ncl`
4. **Test deployment** with dry-run mode: `provisioning -c server create`
5. **Deploy infrastructure** when ready

## Documentation References

- **[Workspace Setup Guide](workspace-setup.md)** - Complete setup instructions
- **[Workspace Switching Guide](workspace-switching-guide.md)** - Managing multiple workspaces
- **[Infrastructure Guide](../infrastructure/infrastructure-management.md)** - Infrastructure details