# TypeDialog Platform Configuration Guide

**Version**: 2.0.0
**Last Updated**: 2026-01-05
**Status**: Production Ready
**Target Audience**: DevOps Engineers, Infrastructure Administrators

**Services Covered**: 8 platform services (orchestrator, control-center, mcp-server, vault-service, extension-registry, rag, ai-service, provisioning-daemon)

Interactive configuration for cloud-native infrastructure platform services using TypeDialog forms and Nickel.

## Overview

**TypeDialog** is an interactive form system that generates Nickel configurations for platform services. Instead of manually editing TOML or KCL files, you answer questions in an interactive form, and TypeDialog generates validated Nickel configuration.

**Benefits**:

- ✅ No manual TOML editing required
- ✅ Interactive guidance for each setting
- ✅ Automatic validation of inputs
- ✅ Type-safe configuration (Nickel contracts)
- ✅ Generated configurations ready for deployment

## Quick Start

### 1. Configure a Platform Service (5 minutes)

```bash
# Launch interactive form for orchestrator
provisioning config platform orchestrator

# Or use TypeDialog directly
typedialog form .typedialog/provisioning/platform/orchestrator/form.toml
```

This opens an interactive form with sections for:

- Workspace configuration
- Server settings (host, port, workers)
- Storage backend (filesystem or SurrealDB)
- Task queue and batch settings
- Monitoring and health checks
- Rollback and recovery
- Logging configuration
- Extensions and integrations
- Advanced settings

### 2. Review Generated Configuration

After completing the form, TypeDialog generates `config.ncl`:

```bash
# View what was generated
cat workspace_librecloud/config/config.ncl
```

### 3. Validate Configuration

```bash
# Check Nickel syntax is valid
nickel typecheck workspace_librecloud/config/config.ncl

# Export to TOML for services
provisioning config export
```

### 4. Services Use Generated Config

Platform services automatically load the exported TOML:

```bash
# Orchestrator reads config/generated/platform/orchestrator.toml
provisioning start orchestrator

# Check it's using the right config
cat workspace_librecloud/config/generated/platform/orchestrator.toml
```

## Interactive Configuration Workflow

### Recommended Approach: Use TypeDialog Forms

**Best for**: Most users, no Nickel knowledge needed

**Workflow**:

1. Launch form for a service: `provisioning config platform orchestrator`
2. Answer questions in interactive prompts about workspace, server, storage, queue
3. Review what was generated: `cat workspace_librecloud/config/config.ncl`
4. Update running services: `provisioning config export && provisioning restart orchestrator`

### Advanced Approach: Manual Nickel Editing

**Best for**: Users comfortable with Nickel, want full control

**Workflow**:

1. Create file: `touch workspace_librecloud/config/config.ncl`
2. Edit directly: `vim workspace_librecloud/config/config.ncl`
3. Validate syntax: `nickel typecheck workspace_librecloud/config/config.ncl`
4. Export and deploy: `provisioning config export && provisioning restart orchestrator`

## Configuration Structure

### Single File, Three Sections

All configuration lives in one Nickel file with three sections:

```nickel
# workspace_librecloud/config/config.ncl
{
  # SECTION 1: Workspace metadata
  workspace = {
    name = "librecloud",
    path = "/Users/Akasha/project-provisioning/workspace_librecloud",
    description = "Production workspace"
  },

  # SECTION 2: Cloud providers
  providers = {
    upcloud = {
      enabled = true,
      api_user = "{{env.UPCLOUD_USER}}",
      api_password = "{{kms.decrypt('upcloud_pass')}}"
    },
    aws = { enabled = false },
    local = { enabled = true }
  },

  # SECTION 3: Platform services
  platform = {
    orchestrator = {
      enabled = true,
      server = { host = "127.0.0.1", port = 9090 },
      storage = { type = "filesystem" }
    },
    kms = {
      enabled = true,
      backend = "rustyvault",
      url = "http://localhost:8200"
    }
  }
}
```

### Available Configuration Sections

| Section | Purpose | Used By |
|---------|---------|---------|
| `workspace` | Workspace metadata and paths | Config loader, providers |
| `providers.upcloud` | UpCloud provider settings | UpCloud provisioning |
| `providers.aws` | AWS provider settings | AWS provisioning |
| `providers.local` | Local VM provider settings | Local VM provisioning |
| **Core Platform Services** | | |
| `platform.orchestrator` | Orchestrator service config | Orchestrator REST API |
| `platform.control_center` | Control center service config | Control center REST API |
| `platform.mcp_server` | MCP server service config | Model Context Protocol integration |
| `platform.installer` | Installer service config | Infrastructure provisioning |
| **Security & Secrets** | | |
| `platform.vault_service` | Vault service config | Secrets management and encryption |
| **Extensions & Registry** | | |
| `platform.extension_registry` | Extension registry config | Extension distribution via Gitea/OCI |
| **AI & Intelligence** | | |
| `platform.rag` | RAG system config | Retrieval-Augmented Generation |
| `platform.ai_service` | AI service config | AI model integration and DAG workflows |
| **Operations & Daemon** | | |
| `platform.provisioning_daemon` | Provisioning daemon config | Background provisioning operations |

## Service-Specific Configuration

### Orchestrator Service

**Purpose**: Coordinate infrastructure operations, manage workflows, handle batch operations

**Key Settings**:

- **server**: HTTP server configuration (host, port, workers)
- **storage**: Task queue storage (filesystem or SurrealDB)
- **queue**: Task processing (concurrency, retries, timeouts)
- **batch**: Batch operation settings (parallelism, timeouts)
- **monitoring**: Health checks and metrics collection
- **rollback**: Checkpoint and recovery strategy
- **logging**: Log level and format

**Example**:

```nickel
platform = {
  orchestrator = {
    enabled = true,
    server = {
      host = "127.0.0.1",
      port = 9090,
      workers = 4,
      keep_alive = 75,
      max_connections = 1000
    },
    storage = {
      type = "filesystem",
      backend_path = "{{workspace.path}}/.orchestrator/data/queue.rkvs"
    },
    queue = {
      max_concurrent_tasks = 5,
      retry_attempts = 3,
      retry_delay_seconds = 5,
      task_timeout_minutes = 60
    }
  }
}
```

### KMS Service

**Purpose**: Cryptographic key management, secret encryption/decryption

**Key Settings**:

- **backend**: KMS backend (rustyvault, age, aws, vault, cosmian)
- **url**: Backend URL or connection string
- **credentials**: Authentication if required

**Example**:

```nickel
platform = {
  kms = {
    enabled = true,
    backend = "rustyvault",
    url = "http://localhost:8200"
  }
}
```

### Control Center Service

**Purpose**: Centralized monitoring and control interface

**Key Settings**:

- **server**: HTTP server configuration
- **database**: Backend database connection
- **jwt**: JWT authentication settings
- **security**: CORS and security policies

**Example**:

```nickel
platform = {
  control_center = {
    enabled = true,
    server = {
      host = "127.0.0.1",
      port = 8080
    }
  }
}
```

## Deployment Modes

All platform services support four deployment modes, each with different resource allocation and feature sets:

| Mode | Resources | Use Case | Storage | TLS |
|------|-----------|----------|---------|-----|
| **solo** | Minimal (2 workers) | Development, testing | Embedded/filesystem | No |
| **multiuser** | Moderate (4 workers) | Team environments | Shared databases | Optional |
| **cicd** | High throughput (8+ workers) | CI/CD pipelines | Ephemeral/memory | No |
| **enterprise** | High availability (16+ workers) | Production | Clustered/distributed | Yes |

**Mode-based Configuration Loading**:

```bash
# Load a specific mode's configuration
export VAULT_MODE=enterprise
export REGISTRY_MODE=multiuser
export RAG_MODE=cicd

# Services automatically resolve to correct TOML files:
# Generated from: provisioning/schemas/platform/
# - vault-service.enterprise.toml (generated from vault-service.ncl)
# - extension-registry.multiuser.toml (generated from extension-registry.ncl)
# - rag.cicd.toml (generated from rag.ncl)
```

## New Platform Services (Phase 13-19)

### Vault Service

**Purpose**: Secrets management, encryption, and cryptographic key storage

**Key Settings**:

- **server**: HTTP server configuration (host, port, workers)
- **storage**: Backend storage (filesystem, memory, surrealdb, etcd, postgresql)
- **vault**: Vault mounting and key management
- **ha**: High availability clustering
- **security**: TLS, certificate validation
- **logging**: Log level and audit trails

**Mode Characteristics**:

- **solo**: Filesystem storage, no TLS, embedded mode
- **multiuser**: SurrealDB backend, shared storage, TLS optional
- **cicd**: In-memory ephemeral storage, no persistence
- **enterprise**: Etcd HA, TLS required, audit logging enabled

**Environment Variable Overrides**:

```bash
VAULT_CONFIG=/path/to/vault.toml              # Explicit config path
VAULT_MODE=enterprise                          # Mode-specific config
VAULT_SERVER_URL=http://localhost:8200        # Server URL
VAULT_STORAGE_BACKEND=etcd                    # Storage backend
VAULT_AUTH_TOKEN=s.xxxxxxxx                   # Authentication token
VAULT_TLS_VERIFY=true                         # TLS verification
```

**Example Configuration**:

```nickel
platform = {
  vault_service = {
    enabled = true,
    server = {
      host = "0.0.0.0",
      port = 8200,
      workers = 8
    },
    storage = {
      backend = "surrealdb",
      url = "http://surrealdb:8000",
      namespace = "vault",
      database = "secrets"
    },
    vault = {
      mount_point = "transit",
      key_name = "provisioning-master"
    },
    ha = {
      enabled = true
    }
  }
}
```

### Extension Registry Service

**Purpose**: Extension distribution and management via Gitea and OCI registries

**Key Settings**:

- **server**: HTTP server configuration (host, port, workers)
- **gitea**: Gitea integration for extension source repository
- **oci**: OCI registry for artifact distribution
- **cache**: Metadata and list caching
- **auth**: Registry authentication

**Mode Characteristics**:

- **solo**: Gitea only, minimal cache, CORS disabled
- **multiuser**: Gitea + OCI, both enabled, CORS enabled
- **cicd**: OCI only (high-throughput mode), ephemeral cache
- **enterprise**: Both Gitea + OCI, TLS verification, large cache

**Environment Variable Overrides**:

```bash
REGISTRY_CONFIG=/path/to/registry.toml       # Explicit config path
REGISTRY_MODE=multiuser                       # Mode-specific config
REGISTRY_SERVER_HOST=0.0.0.0                 # Server host
REGISTRY_SERVER_PORT=8081                    # Server port
REGISTRY_SERVER_WORKERS=4                    # Worker count
REGISTRY_GITEA_URL=http://gitea:3000         # Gitea URL
REGISTRY_GITEA_ORG=provisioning              # Gitea organization
REGISTRY_OCI_REGISTRY=registry.local:5000     # OCI registry
REGISTRY_OCI_NAMESPACE=provisioning          # OCI namespace
```

**Example Configuration**:

```nickel
platform = {
  extension_registry = {
    enabled = true,
    server = {
      host = "0.0.0.0",
      port = 8081,
      workers = 4
    },
    gitea = {
      enabled = true,
      url = "http://gitea:3000",
      org = "provisioning"
    },
    oci = {
      enabled = true,
      registry = "registry.local:5000",
      namespace = "provisioning"
    },
    cache = {
      capacity = 1000,
      ttl = 300
    }
  }
}
```

### RAG (Retrieval-Augmented Generation) Service

**Purpose**: Document retrieval, semantic search, and AI-augmented responses

**Key Settings**:

- **embeddings**: Embedding model provider (openai, local, anthropic)
- **vector_db**: Vector database backend (memory, surrealdb, qdrant, milvus)
- **llm**: Language model provider (anthropic, openai, ollama)
- **retrieval**: Search strategy and parameters
- **ingestion**: Document processing and indexing

**Mode Characteristics**:

- **solo**: Local embeddings, in-memory vector DB, Ollama LLM
- **multiuser**: OpenAI embeddings, SurrealDB vector DB, Anthropic LLM
- **cicd**: **RAG completely disabled** (not applicable for ephemeral pipelines)
- **enterprise**: Large embeddings (3072-dim), distributed vector DB, Claude Opus

**Environment Variable Overrides**:

```bash
RAG_CONFIG=/path/to/rag.toml                 # Explicit config path
RAG_MODE=multiuser                            # Mode-specific config
RAG_ENABLED=true                              # Enable/disable RAG
RAG_EMBEDDINGS_PROVIDER=openai               # Embedding provider
RAG_EMBEDDINGS_API_KEY=sk-xxx                # Embedding API key
RAG_VECTOR_DB_URL=http://surrealdb:8000     # Vector DB URL
RAG_LLM_PROVIDER=anthropic                   # LLM provider
RAG_LLM_API_KEY=sk-ant-xxx                  # LLM API key
RAG_VECTOR_DB_TYPE=surrealdb                # Vector DB type
```

**Example Configuration**:

```nickel
platform = {
  rag = {
    enabled = true,
    embeddings = {
      provider = "openai",
      model = "text-embedding-3-small",
      api_key = "{{env.OPENAI_API_KEY}}"
    },
    vector_db = {
      db_type = "surrealdb",
      url = "http://surrealdb:8000",
      namespace = "rag_prod"
    },
    llm = {
      provider = "anthropic",
      model = "claude-opus-4-5-20251101",
      api_key = "{{env.ANTHROPIC_API_KEY}}"
    },
    retrieval = {
      top_k = 10,
      similarity_threshold = 0.75
    }
  }
}
```

### AI Service

**Purpose**: AI model integration with RAG and MCP support for multi-step workflows

**Key Settings**:

- **server**: HTTP server configuration
- **rag**: RAG system integration
- **mcp**: Model Context Protocol integration
- **dag**: Directed acyclic graph task orchestration

**Mode Characteristics**:

- **solo**: RAG enabled, no MCP, minimal concurrency (3 tasks)
- **multiuser**: Both RAG and MCP enabled, moderate concurrency (10 tasks)
- **cicd**: RAG disabled, MCP enabled, high concurrency (20 tasks)
- **enterprise**: Both enabled, max concurrency (50 tasks), full monitoring

**Environment Variable Overrides**:

```bash
AI_SERVICE_CONFIG=/path/to/ai.toml           # Explicit config path
AI_SERVICE_MODE=enterprise                    # Mode-specific config
AI_SERVICE_SERVER_PORT=8082                  # Server port
AI_SERVICE_SERVER_WORKERS=16                 # Worker count
AI_SERVICE_RAG_ENABLED=true                  # Enable RAG integration
AI_SERVICE_MCP_ENABLED=true                  # Enable MCP integration
AI_SERVICE_DAG_MAX_CONCURRENT_TASKS=50       # Max concurrent tasks
```

**Example Configuration**:

```nickel
platform = {
  ai_service = {
    enabled = true,
    server = {
      host = "0.0.0.0",
      port = 8082,
      workers = 8
    },
    rag = {
      enabled = true,
      rag_service_url = "http://rag:8083",
      timeout = 60000
    },
    mcp = {
      enabled = true,
      mcp_service_url = "http://mcp-server:8084",
      timeout = 60000
    },
    dag = {
      max_concurrent_tasks = 20,
      task_timeout = 600000,
      retry_attempts = 5
    }
  }
}
```

### Provisioning Daemon

**Purpose**: Background service for provisioning operations, workspace management, and health monitoring

**Key Settings**:

- **daemon**: Daemon control (poll interval, max workers)
- **logging**: Log level and output configuration
- **actions**: Automated actions (cleanup, updates, sync)
- **workers**: Worker pool configuration
- **health**: Health check settings

**Mode Characteristics**:

- **solo**: Minimal polling, no auto-cleanup, debug logging
- **multiuser**: Standard polling, workspace sync enabled, info logging
- **cicd**: Frequent polling, ephemeral cleanup, warning logging
- **enterprise**: Standard polling, full automation, all features enabled

**Environment Variable Overrides**:

```bash
DAEMON_CONFIG=/path/to/daemon.toml           # Explicit config path
DAEMON_MODE=enterprise                        # Mode-specific config
DAEMON_POLL_INTERVAL=30                      # Polling interval (seconds)
DAEMON_MAX_WORKERS=16                        # Maximum worker threads
DAEMON_LOGGING_LEVEL=info                    # Log level (debug/info/warn/error)
DAEMON_AUTO_CLEANUP=true                     # Enable auto cleanup
DAEMON_AUTO_UPDATE=true                      # Enable auto updates
```

**Example Configuration**:

```nickel
platform = {
  provisioning_daemon = {
    enabled = true,
    daemon = {
      poll_interval = 30,
      max_workers = 8
    },
    logging = {
      level = "info",
      file = "/var/log/provisioning/daemon.log"
    },
    actions = {
      auto_cleanup = true,
      auto_update = false,
      workspace_sync = true
    }
  }
}
```

## Using TypeDialog Forms

### Form Navigation

1. **Interactive Prompts**: Answer questions one at a time
2. **Validation**: Inputs are validated as you type
3. **Defaults**: Each field shows a sensible default
4. **Skip Optional**: Press Enter to use default or skip optional fields
5. **Review**: Preview generated Nickel before saving

### Field Types

| Type | Example | Notes |
|------|---------|-------|
| `text` | "127.0.0.1" | Free-form text input |
| `confirm` | true/false | Yes/no answer |
| `select` | "filesystem" | Choose from list |
| `custom(u16)` | 9090 | Number input |
| `custom(u32)` | 1000 | Larger number |

### Special Values

**Environment Variables**:

```nickel
api_user = "{{env.UPCLOUD_USER}}"
api_password = "{{env.UPCLOUD_PASSWORD}}"
```

**Workspace Paths**:

```nickel
data_dir = "{{workspace.path}}/.orchestrator/data"
logs_dir = "{{workspace.path}}/.orchestrator/logs"
```

**KMS Decryption**:

```nickel
api_password = "{{kms.decrypt('upcloud_pass')}}"
```

## Validation & Export

### Validating Configuration

```bash
# Check Nickel syntax
nickel typecheck workspace_librecloud/config/config.ncl

# Detailed validation with error messages
nickel typecheck workspace_librecloud/config/config.ncl 2>&1

# Schema validation happens during export
provisioning config export
```

### Exporting to Service Formats

```bash
# One-time export
provisioning config export

# Export creates (pre-configured TOML for all services):
workspace_librecloud/config/generated/
├── workspace.toml          # Workspace metadata
├── providers/
│   ├── upcloud.toml        # UpCloud provider
│   └── local.toml          # Local provider
└── platform/
    ├── orchestrator.toml   # Orchestrator service
    ├── control_center.toml # Control center service
    ├── mcp_server.toml     # MCP server service
    ├── installer.toml      # Installer service
    ├── kms.toml            # KMS service
    ├── vault_service.toml  # Vault service (new)
    ├── extension_registry.toml  # Extension registry (new)
    ├── rag.toml            # RAG service (new)
    ├── ai_service.toml     # AI service (new)
    └── provisioning_daemon.toml # Daemon service (new)

# Public Nickel Schemas (20 total for 5 new services):
provisioning/schemas/platform/
├── schemas/
│   ├── vault-service.ncl
│   ├── extension-registry.ncl
│   ├── rag.ncl
│   ├── ai-service.ncl
│   └── provisioning-daemon.ncl
├── defaults/
│   ├── vault-service-defaults.ncl
│   ├── extension-registry-defaults.ncl
│   ├── rag-defaults.ncl
│   ├── ai-service-defaults.ncl
│   ├── provisioning-daemon-defaults.ncl
│   └── deployment/
│       ├── solo-defaults.ncl
│       ├── multiuser-defaults.ncl
│       ├── cicd-defaults.ncl
│       └── enterprise-defaults.ncl
├── validators/
├── templates/
├── constraints/
└── values/
```

**Using Pre-Generated Configurations**:

All 5 new services come with pre-built TOML configs for each deployment mode:

```bash
# View available schemas for vault service
ls -la provisioning/schemas/platform/schemas/vault-service.ncl
ls -la provisioning/schemas/platform/defaults/vault-service-defaults.ncl

# Load enterprise mode
export VAULT_MODE=enterprise
cargo run -p vault-service

# Or load multiuser mode
export REGISTRY_MODE=multiuser
cargo run -p extension-registry

# All 5 services support mode-based loading
export RAG_MODE=cicd
export AI_SERVICE_MODE=enterprise
export DAEMON_MODE=multiuser
```

## Updating Configuration

### Change a Setting

1. **Edit source config**: `vim workspace_librecloud/config/config.ncl`
2. **Validate changes**: `nickel typecheck workspace_librecloud/config/config.ncl`
3. **Re-export to TOML**: `provisioning config export`
4. **Restart affected service** (if needed): `provisioning restart orchestrator`

### Using TypeDialog to Update

If you prefer interactive updating:

```bash
# Re-run TypeDialog form (overwrites config.ncl)
provisioning config platform orchestrator

# Or edit via TypeDialog with existing values
typedialog form .typedialog/provisioning/platform/orchestrator/form.toml
```

## Troubleshooting

### Form Won't Load

**Problem**: `Failed to parse config file`

**Solution**: Check form.toml syntax and verify required fields are present (name, description, locales_path, templates_path)

```bash
head -10 .typedialog/provisioning/platform/orchestrator/form.toml
```

### Validation Fails

**Problem**: `Nickel configuration validation failed`

**Solution**: Check for syntax errors and correct field names

```bash
nickel typecheck workspace_librecloud/config/config.ncl 2>&1 | less
```

Common issues: Missing closing braces, incorrect field names, wrong data types

### Export Creates Empty Files

**Problem**: Generated TOML files are empty

**Solution**: Verify config.ncl exports to JSON and check all required sections exist

```bash
nickel export --format json workspace_librecloud/config/config.ncl | head -20
```

### Services Don't Use New Config

**Problem**: Changes don't take effect

**Solution**:

1. Verify export succeeded: `ls -lah workspace_librecloud/config/generated/platform/`
2. Check service path: `provisioning start orchestrator --check`
3. Restart service: `provisioning restart orchestrator`

## Configuration Examples

### Development Setup

```nickel
{
  workspace = {
    name = "dev",
    path = "/Users/dev/workspace",
    description = "Development workspace"
  },

  providers = {
    local = {
      enabled = true,
      base_path = "/opt/vms"
    },
    upcloud = { enabled = false },
    aws = { enabled = false }
  },

  platform = {
    orchestrator = {
      enabled = true,
      server = { host = "127.0.0.1", port = 9090 },
      storage = { type = "filesystem" },
      logging = { level = "debug", format = "json" }
    },
    kms = {
      enabled = true,
      backend = "age"
    }
  }
}
```

### Production Setup

```nickel
{
  workspace = {
    name = "prod",
    path = "/opt/provisioning/prod",
    description = "Production workspace"
  },

  providers = {
    upcloud = {
      enabled = true,
      api_user = "{{env.UPCLOUD_USER}}",
      api_password = "{{kms.decrypt('upcloud_prod')}}",
      default_zone = "de-fra1"
    },
    aws = { enabled = false },
    local = { enabled = false }
  },

  platform = {
    orchestrator = {
      enabled = true,
      server = { host = "0.0.0.0", port = 9090, workers = 8 },
      storage = {
        type = "surrealdb-server",
        url = "ws://surreal.internal:8000"
      },
      monitoring = {
        enabled = true,
        metrics_interval_seconds = 30
      },
      logging = { level = "info", format = "json" }
    },
    kms = {
      enabled = true,
      backend = "vault",
      url = "https://vault.internal:8200"
    }
  }
}
```

### Multi-Provider Setup

```nickel
{
  workspace = {
    name = "multi",
    path = "/opt/multi",
    description = "Multi-cloud workspace"
  },

  providers = {
    upcloud = {
      enabled = true,
      api_user = "{{env.UPCLOUD_USER}}",
      default_zone = "de-fra1",
      zones = ["de-fra1", "us-nyc1", "nl-ams1"]
    },
    aws = {
      enabled = true,
      access_key = "{{env.AWS_ACCESS_KEY_ID}}"
    },
    local = {
      enabled = true,
      base_path = "/opt/local-vms"
    }
  },

  platform = {
    orchestrator = {
      enabled = true,
      multi_workspace = false,
      storage = { type = "filesystem" }
    },
    kms = {
      enabled = true,
      backend = "rustyvault"
    }
  }
}
```

## Best Practices

### 1. Use TypeDialog for Initial Setup

Start with TypeDialog forms for the best experience:

```bash
provisioning config platform orchestrator
```

### 2. Never Edit Generated Files

Only edit the source `.ncl` file, not the generated TOML files.

**Correct**: `vim workspace_librecloud/config/config.ncl`

**Wrong**: `vim workspace_librecloud/config/generated/platform/orchestrator.toml`

### 3. Validate Before Deploy

Always validate before deploying changes:

```bash
nickel typecheck workspace_librecloud/config/config.ncl
provisioning config export
```

### 4. Use Environment Variables for Secrets

Never hardcode credentials in config. Reference environment variables or KMS:

**Wrong**: `api_password = "my-password"`

**Correct**: `api_password = "{{env.UPCLOUD_PASSWORD}}"`

**Better**: `api_password = "{{kms.decrypt('upcloud_key')}}"`

### 5. Document Changes

Add comments explaining custom settings in the Nickel file.

## Related Documentation

### Core Resources
- **Configuration System**: See `CLAUDE.md#configuration-file-format-selection`
- **Migration Guide**: See `provisioning/config/README.md#migration-strategy`
- **Schema Reference**: See `provisioning/schemas/`
- **Nickel Language**: See ADR-011 in `docs/architecture/adr/`

### Platform Services
- **Platform Services Overview**: See `provisioning/platform/*/README.md`
- **Core Services** (Phases 8-12): orchestrator, control-center, mcp-server
- **New Services** (Phases 13-19):
  - vault-service: Secrets management and encryption
  - extension-registry: Extension distribution via Gitea/OCI
  - rag: Retrieval-Augmented Generation system
  - ai-service: AI model integration with DAG workflows
  - provisioning-daemon: Background provisioning operations

**Note**: Installer is a distribution tool (provisioning/tools/distribution/create-installer.nu), not a platform service configurable via TypeDialog.

### Public Definition Locations
- **TypeDialog Forms** (Interactive UI): `provisioning/.typedialog/platform/forms/`
- **Nickel Schemas** (Type Definitions): `provisioning/schemas/platform/schemas/`
- **Default Values** (Base Configuration): `provisioning/schemas/platform/defaults/`
- **Validators** (Business Logic): `provisioning/schemas/platform/validators/`
- **Deployment Modes** (Presets): `provisioning/schemas/platform/defaults/deployment/`
- **Rust Integration**: `provisioning/platform/crates/*/src/config.rs`

## Getting Help

### Validation Errors

Get detailed error messages and check available fields:

```bash
nickel typecheck workspace_librecloud/config/config.ncl 2>&1 | less
grep "prompt =" .typedialog/provisioning/platform/orchestrator/form.toml
```

### Configuration Questions

```bash
# Show all available config commands
provisioning config --help

# Show help for specific service
provisioning config platform --help

# List providers and services
provisioning config providers list
provisioning config services list
```

### Test Configuration

```bash
# Validate without deploying
nickel typecheck workspace_librecloud/config/config.ncl

# Export to see generated config
provisioning config export

# Check generated files
ls -la workspace_librecloud/config/generated/
```
