# TypeDialog Platform Configuration Guide\n\n**Version**: 2.0.0\n**Last Updated**: 2026-01-05\n**Status**: Production Ready\n**Target Audience**: DevOps Engineers, Infrastructure Administrators\n\n**Services Covered**: 8 platform services (orchestrator, control-center, mcp-server, vault-service, extension-registry, rag, ai-service,\nprovisioning-daemon)\n\nInteractive configuration for cloud-native infrastructure platform services using TypeDialog forms and Nickel.\n\n## Overview\n\n**TypeDialog** is an interactive form system that generates Nickel configurations for platform services. Instead of manually editing TOML or KCL\nfiles, you answer questions in an interactive form, and TypeDialog generates validated Nickel configuration.\n\n**Benefits**:\n\n- ✅ No manual TOML editing required\n- ✅ Interactive guidance for each setting\n- ✅ Automatic validation of inputs\n- ✅ Type-safe configuration (Nickel contracts)\n- ✅ Generated configurations ready for deployment\n\n## Quick Start\n\n### 1. Configure a Platform Service (5 minutes)\n\n```\n# Launch interactive form for orchestrator\nprovisioning config platform orchestrator\n\n# Or use TypeDialog directly\ntypedialog form .typedialog/provisioning/platform/orchestrator/form.toml\n```\n\nThis opens an interactive form with sections for:\n\n- Workspace configuration\n- Server settings (host, port, workers)\n- Storage backend (filesystem or SurrealDB)\n- Task queue and batch settings\n- Monitoring and health checks\n- Rollback and recovery\n- Logging configuration\n- Extensions and integrations\n- Advanced settings\n\n### 2. Review Generated Configuration\n\nAfter completing the form, TypeDialog generates `config.ncl`:\n\n```\n# View what was generated\ncat workspace_librecloud/config/config.ncl\n```\n\n### 3. Validate Configuration\n\n```\n# Check Nickel syntax is valid\nnickel typecheck workspace_librecloud/config/config.ncl\n\n# Export to TOML for services\nprovisioning config export\n```\n\n### 4. Services Use Generated Config\n\nPlatform services automatically load the exported TOML:\n\n```\n# Orchestrator reads config/generated/platform/orchestrator.toml\nprovisioning start orchestrator\n\n# Check it's using the right config\ncat workspace_librecloud/config/generated/platform/orchestrator.toml\n```\n\n## Interactive Configuration Workflow\n\n### Recommended Approach: Use TypeDialog Forms\n\n**Best for**: Most users, no Nickel knowledge needed\n\n**Workflow**:\n\n1. Launch form for a service: `provisioning config platform orchestrator`\n2. Answer questions in interactive prompts about workspace, server, storage, queue\n3. Review what was generated: `cat workspace_librecloud/config/config.ncl`\n4. Update running services: `provisioning config export && provisioning restart orchestrator`\n\n### Advanced Approach: Manual Nickel Editing\n\n**Best for**: Users comfortable with Nickel, want full control\n\n**Workflow**:\n\n1. Create file: `touch workspace_librecloud/config/config.ncl`\n2. Edit directly: `vim workspace_librecloud/config/config.ncl`\n3. Validate syntax: `nickel typecheck workspace_librecloud/config/config.ncl`\n4. Export and deploy: `provisioning config export && provisioning restart orchestrator`\n\n## Configuration Structure\n\n### Single File, Three Sections\n\nAll configuration lives in one Nickel file with three sections:\n\n```\n# workspace_librecloud/config/config.ncl\n{\n  # SECTION 1: Workspace metadata\n  workspace = {\n    name = "librecloud",\n    path = "/Users/Akasha/project-provisioning/workspace_librecloud",\n    description = "Production workspace"\n  },\n\n  # SECTION 2: Cloud providers\n  providers = {\n    upcloud = {\n      enabled = true,\n      api_user = "{{env.UPCLOUD_USER}}",\n      api_password = "{{kms.decrypt('upcloud_pass')}}"\n    },\n    aws = { enabled = false },\n    local = { enabled = true }\n  },\n\n  # SECTION 3: Platform services\n  platform = {\n    orchestrator = {\n      enabled = true,\n      server = { host = "127.0.0.1", port = 9090 },\n      storage = { type = "filesystem" }\n    },\n    kms = {\n      enabled = true,\n      backend = "rustyvault",\n      url = "http://localhost:8200"\n    }\n  }\n}\n```\n\n### Available Configuration Sections\n\n| Section | Purpose | Used By |\n| --------- | --------- | --------- |\n| `workspace` | Workspace metadata and paths | Config loader, providers |\n| `providers.upcloud` | UpCloud provider settings | UpCloud provisioning |\n| `providers.aws` | AWS provider settings | AWS provisioning |\n| `providers.local` | Local VM provider settings | Local VM provisioning |\n| **Core Platform Services** | | |\n| `platform.orchestrator` | Orchestrator service config | Orchestrator REST API |\n| `platform.control_center` | Control center service config | Control center REST API |\n| `platform.mcp_server` | MCP server service config | Model Context Protocol integration |\n| `platform.installer` | Installer service config | Infrastructure provisioning |\n| **Security & Secrets** | | |\n| `platform.vault_service` | Vault service config | Secrets management and encryption |\n| **Extensions & Registry** | | |\n| `platform.extension_registry` | Extension registry config | Extension distribution via Gitea/OCI |\n| **AI & Intelligence** | | |\n| `platform.rag` | RAG system config | Retrieval-Augmented Generation |\n| `platform.ai_service` | AI service config | AI model integration and DAG workflows |\n| **Operations & Daemon** | | |\n| `platform.provisioning_daemon` | Provisioning daemon config | Background provisioning operations |\n\n## Service-Specific Configuration\n\n### Orchestrator Service\n\n**Purpose**: Coordinate infrastructure operations, manage workflows, handle batch operations\n\n**Key Settings**:\n\n- **server**: HTTP server configuration (host, port, workers)\n- **storage**: Task queue storage (filesystem or SurrealDB)\n- **queue**: Task processing (concurrency, retries, timeouts)\n- **batch**: Batch operation settings (parallelism, timeouts)\n- **monitoring**: Health checks and metrics collection\n- **rollback**: Checkpoint and recovery strategy\n- **logging**: Log level and format\n\n**Example**:\n\n```\nplatform = {\n  orchestrator = {\n    enabled = true,\n    server = {\n      host = "127.0.0.1",\n      port = 9090,\n      workers = 4,\n      keep_alive = 75,\n      max_connections = 1000\n    },\n    storage = {\n      type = "filesystem",\n      backend_path = "{{workspace.path}}/.orchestrator/data/queue.rkvs"\n    },\n    queue = {\n      max_concurrent_tasks = 5,\n      retry_attempts = 3,\n      retry_delay_seconds = 5,\n      task_timeout_minutes = 60\n    }\n  }\n}\n```\n\n### KMS Service\n\n**Purpose**: Cryptographic key management, secret encryption/decryption\n\n**Key Settings**:\n\n- **backend**: KMS backend (rustyvault, age, aws, vault, cosmian)\n- **url**: Backend URL or connection string\n- **credentials**: Authentication if required\n\n**Example**:\n\n```\nplatform = {\n  kms = {\n    enabled = true,\n    backend = "rustyvault",\n    url = "http://localhost:8200"\n  }\n}\n```\n\n### Control Center Service\n\n**Purpose**: Centralized monitoring and control interface\n\n**Key Settings**:\n\n- **server**: HTTP server configuration\n- **database**: Backend database connection\n- **jwt**: JWT authentication settings\n- **security**: CORS and security policies\n\n**Example**:\n\n```\nplatform = {\n  control_center = {\n    enabled = true,\n    server = {\n      host = "127.0.0.1",\n      port = 8080\n    }\n  }\n}\n```\n\n## Deployment Modes\n\nAll platform services support four deployment modes, each with different resource allocation and feature sets:\n\n| Mode | Resources | Use Case | Storage | TLS |\n| ------ | ----------- | ---------- | --------- | ----- |\n| **solo** | Minimal (2 workers) | Development, testing | Embedded/filesystem | No |\n| **multiuser** | Moderate (4 workers) | Team environments | Shared databases | Optional |\n| **cicd** | High throughput (8+ workers) | CI/CD pipelines | Ephemeral/memory | No |\n| **enterprise** | High availability (16+ workers) | Production | Clustered/distributed | Yes |\n\n**Mode-based Configuration Loading**:\n\n```\n# Load a specific mode's configuration\nexport VAULT_MODE=enterprise\nexport REGISTRY_MODE=multiuser\nexport RAG_MODE=cicd\n\n# Services automatically resolve to correct TOML files:\n# Generated from: provisioning/schemas/platform/\n# - vault-service.enterprise.toml (generated from vault-service.ncl)\n# - extension-registry.multiuser.toml (generated from extension-registry.ncl)\n# - rag.cicd.toml (generated from rag.ncl)\n```\n\n## New Platform Services (Phase 13-19)\n\n### Vault Service\n\n**Purpose**: Secrets management, encryption, and cryptographic key storage\n\n**Key Settings**:\n\n- **server**: HTTP server configuration (host, port, workers)\n- **storage**: Backend storage (filesystem, memory, surrealdb, etcd, postgresql)\n- **vault**: Vault mounting and key management\n- **ha**: High availability clustering\n- **security**: TLS, certificate validation\n- **logging**: Log level and audit trails\n\n**Mode Characteristics**:\n\n- **solo**: Filesystem storage, no TLS, embedded mode\n- **multiuser**: SurrealDB backend, shared storage, TLS optional\n- **cicd**: In-memory ephemeral storage, no persistence\n- **enterprise**: Etcd HA, TLS required, audit logging enabled\n\n**Environment Variable Overrides**:\n\n```\nVAULT_CONFIG=/path/to/vault.toml              # Explicit config path\nVAULT_MODE=enterprise                          # Mode-specific config\nVAULT_SERVER_URL=http://localhost:8200        # Server URL\nVAULT_STORAGE_BACKEND=etcd                    # Storage backend\nVAULT_AUTH_TOKEN=s.xxxxxxxx                   # Authentication token\nVAULT_TLS_VERIFY=true                         # TLS verification\n```\n\n**Example Configuration**:\n\n```\nplatform = {\n  vault_service = {\n    enabled = true,\n    server = {\n      host = "0.0.0.0",\n      port = 8200,\n      workers = 8\n    },\n    storage = {\n      backend = "surrealdb",\n      url = "http://surrealdb:8000",\n      namespace = "vault",\n      database = "secrets"\n    },\n    vault = {\n      mount_point = "transit",\n      key_name = "provisioning-master"\n    },\n    ha = {\n      enabled = true\n    }\n  }\n}\n```\n\n### Extension Registry Service\n\n**Purpose**: Extension distribution and management via Gitea and OCI registries\n\n**Key Settings**:\n\n- **server**: HTTP server configuration (host, port, workers)\n- **gitea**: Gitea integration for extension source repository\n- **oci**: OCI registry for artifact distribution\n- **cache**: Metadata and list caching\n- **auth**: Registry authentication\n\n**Mode Characteristics**:\n\n- **solo**: Gitea only, minimal cache, CORS disabled\n- **multiuser**: Gitea + OCI, both enabled, CORS enabled\n- **cicd**: OCI only (high-throughput mode), ephemeral cache\n- **enterprise**: Both Gitea + OCI, TLS verification, large cache\n\n**Environment Variable Overrides**:\n\n```\nREGISTRY_CONFIG=/path/to/registry.toml       # Explicit config path\nREGISTRY_MODE=multiuser                       # Mode-specific config\nREGISTRY_SERVER_HOST=0.0.0.0                 # Server host\nREGISTRY_SERVER_PORT=8081                    # Server port\nREGISTRY_SERVER_WORKERS=4                    # Worker count\nREGISTRY_GITEA_URL=http://gitea:3000         # Gitea URL\nREGISTRY_GITEA_ORG=provisioning              # Gitea organization\nREGISTRY_OCI_REGISTRY=registry.local:5000     # OCI registry\nREGISTRY_OCI_NAMESPACE=provisioning          # OCI namespace\n```\n\n**Example Configuration**:\n\n```\nplatform = {\n  extension_registry = {\n    enabled = true,\n    server = {\n      host = "0.0.0.0",\n      port = 8081,\n      workers = 4\n    },\n    gitea = {\n      enabled = true,\n      url = "http://gitea:3000",\n      org = "provisioning"\n    },\n    oci = {\n      enabled = true,\n      registry = "registry.local:5000",\n      namespace = "provisioning"\n    },\n    cache = {\n      capacity = 1000,\n      ttl = 300\n    }\n  }\n}\n```\n\n### RAG (Retrieval-Augmented Generation) Service\n\n**Purpose**: Document retrieval, semantic search, and AI-augmented responses\n\n**Key Settings**:\n\n- **embeddings**: Embedding model provider (openai, local, anthropic)\n- **vector_db**: Vector database backend (memory, surrealdb, qdrant, milvus)\n- **llm**: Language model provider (anthropic, openai, ollama)\n- **retrieval**: Search strategy and parameters\n- **ingestion**: Document processing and indexing\n\n**Mode Characteristics**:\n\n- **solo**: Local embeddings, in-memory vector DB, Ollama LLM\n- **multiuser**: OpenAI embeddings, SurrealDB vector DB, Anthropic LLM\n- **cicd**: **RAG completely disabled** (not applicable for ephemeral pipelines)\n- **enterprise**: Large embeddings (3072-dim), distributed vector DB, Claude Opus\n\n**Environment Variable Overrides**:\n\n```\nRAG_CONFIG=/path/to/rag.toml                 # Explicit config path\nRAG_MODE=multiuser                            # Mode-specific config\nRAG_ENABLED=true                              # Enable/disable RAG\nRAG_EMBEDDINGS_PROVIDER=openai               # Embedding provider\nRAG_EMBEDDINGS_API_KEY=sk-xxx                # Embedding API key\nRAG_VECTOR_DB_URL=http://surrealdb:8000     # Vector DB URL\nRAG_LLM_PROVIDER=anthropic                   # LLM provider\nRAG_LLM_API_KEY=sk-ant-xxx                  # LLM API key\nRAG_VECTOR_DB_TYPE=surrealdb                # Vector DB type\n```\n\n**Example Configuration**:\n\n```\nplatform = {\n  rag = {\n    enabled = true,\n    embeddings = {\n      provider = "openai",\n      model = "text-embedding-3-small",\n      api_key = "{{env.OPENAI_API_KEY}}"\n    },\n    vector_db = {\n      db_type = "surrealdb",\n      url = "http://surrealdb:8000",\n      namespace = "rag_prod"\n    },\n    llm = {\n      provider = "anthropic",\n      model = "claude-opus-4-5-20251101",\n      api_key = "{{env.ANTHROPIC_API_KEY}}"\n    },\n    retrieval = {\n      top_k = 10,\n      similarity_threshold = 0.75\n    }\n  }\n}\n```\n\n### AI Service\n\n**Purpose**: AI model integration with RAG and MCP support for multi-step workflows\n\n**Key Settings**:\n\n- **server**: HTTP server configuration\n- **rag**: RAG system integration\n- **mcp**: Model Context Protocol integration\n- **dag**: Directed acyclic graph task orchestration\n\n**Mode Characteristics**:\n\n- **solo**: RAG enabled, no MCP, minimal concurrency (3 tasks)\n- **multiuser**: Both RAG and MCP enabled, moderate concurrency (10 tasks)\n- **cicd**: RAG disabled, MCP enabled, high concurrency (20 tasks)\n- **enterprise**: Both enabled, max concurrency (50 tasks), full monitoring\n\n**Environment Variable Overrides**:\n\n```\nAI_SERVICE_CONFIG=/path/to/ai.toml           # Explicit config path\nAI_SERVICE_MODE=enterprise                    # Mode-specific config\nAI_SERVICE_SERVER_PORT=8082                  # Server port\nAI_SERVICE_SERVER_WORKERS=16                 # Worker count\nAI_SERVICE_RAG_ENABLED=true                  # Enable RAG integration\nAI_SERVICE_MCP_ENABLED=true                  # Enable MCP integration\nAI_SERVICE_DAG_MAX_CONCURRENT_TASKS=50       # Max concurrent tasks\n```\n\n**Example Configuration**:\n\n```\nplatform = {\n  ai_service = {\n    enabled = true,\n    server = {\n      host = "0.0.0.0",\n      port = 8082,\n      workers = 8\n    },\n    rag = {\n      enabled = true,\n      rag_service_url = "http://rag:8083",\n      timeout = 60000\n    },\n    mcp = {\n      enabled = true,\n      mcp_service_url = "http://mcp-server:8084",\n      timeout = 60000\n    },\n    dag = {\n      max_concurrent_tasks = 20,\n      task_timeout = 600000,\n      retry_attempts = 5\n    }\n  }\n}\n```\n\n### Provisioning Daemon\n\n**Purpose**: Background service for provisioning operations, workspace management, and health monitoring\n\n**Key Settings**:\n\n- **daemon**: Daemon control (poll interval, max workers)\n- **logging**: Log level and output configuration\n- **actions**: Automated actions (cleanup, updates, sync)\n- **workers**: Worker pool configuration\n- **health**: Health check settings\n\n**Mode Characteristics**:\n\n- **solo**: Minimal polling, no auto-cleanup, debug logging\n- **multiuser**: Standard polling, workspace sync enabled, info logging\n- **cicd**: Frequent polling, ephemeral cleanup, warning logging\n- **enterprise**: Standard polling, full automation, all features enabled\n\n**Environment Variable Overrides**:\n\n```\nDAEMON_CONFIG=/path/to/daemon.toml           # Explicit config path\nDAEMON_MODE=enterprise                        # Mode-specific config\nDAEMON_POLL_INTERVAL=30                      # Polling interval (seconds)\nDAEMON_MAX_WORKERS=16                        # Maximum worker threads\nDAEMON_LOGGING_LEVEL=info                    # Log level (debug/info/warn/error)\nDAEMON_AUTO_CLEANUP=true                     # Enable auto cleanup\nDAEMON_AUTO_UPDATE=true                      # Enable auto updates\n```\n\n**Example Configuration**:\n\n```\nplatform = {\n  provisioning_daemon = {\n    enabled = true,\n    daemon = {\n      poll_interval = 30,\n      max_workers = 8\n    },\n    logging = {\n      level = "info",\n      file = "/var/log/provisioning/daemon.log"\n    },\n    actions = {\n      auto_cleanup = true,\n      auto_update = false,\n      workspace_sync = true\n    }\n  }\n}\n```\n\n## Using TypeDialog Forms\n\n### Form Navigation\n\n1. **Interactive Prompts**: Answer questions one at a time\n2. **Validation**: Inputs are validated as you type\n3. **Defaults**: Each field shows a sensible default\n4. **Skip Optional**: Press Enter to use default or skip optional fields\n5. **Review**: Preview generated Nickel before saving\n\n### Field Types\n\n| Type | Example | Notes |\n| ------ | --------- | ------- |\n| `text` | "127.0.0.1" | Free-form text input |\n| `confirm` | true/false | Yes/no answer |\n| `select` | "filesystem" | Choose from list |\n| `custom(u16)` | 9090 | Number input |\n| `custom(u32)` | 1000 | Larger number |\n\n### Special Values\n\n**Environment Variables**:\n\n```\napi_user = "{{env.UPCLOUD_USER}}"\napi_password = "{{env.UPCLOUD_PASSWORD}}"\n```\n\n**Workspace Paths**:\n\n```\ndata_dir = "{{workspace.path}}/.orchestrator/data"\nlogs_dir = "{{workspace.path}}/.orchestrator/logs"\n```\n\n**KMS Decryption**:\n\n```\napi_password = "{{kms.decrypt('upcloud_pass')}}"\n```\n\n## Validation & Export\n\n### Validating Configuration\n\n```\n# Check Nickel syntax\nnickel typecheck workspace_librecloud/config/config.ncl\n\n# Detailed validation with error messages\nnickel typecheck workspace_librecloud/config/config.ncl 2>&1\n\n# Schema validation happens during export\nprovisioning config export\n```\n\n### Exporting to Service Formats\n\n```\n# One-time export\nprovisioning config export\n\n# Export creates (pre-configured TOML for all services):\nworkspace_librecloud/config/generated/\n├── workspace.toml          # Workspace metadata\n├── providers/\n│   ├── upcloud.toml        # UpCloud provider\n│   └── local.toml          # Local provider\n└── platform/\n    ├── orchestrator.toml   # Orchestrator service\n    ├── control_center.toml # Control center service\n    ├── mcp_server.toml     # MCP server service\n    ├── installer.toml      # Installer service\n    ├── kms.toml            # KMS service\n    ├── vault_service.toml  # Vault service (new)\n    ├── extension_registry.toml  # Extension registry (new)\n    ├── rag.toml            # RAG service (new)\n    ├── ai_service.toml     # AI service (new)\n    └── provisioning_daemon.toml # Daemon service (new)\n\n# Public Nickel Schemas (20 total for 5 new services):\nprovisioning/schemas/platform/\n├── schemas/\n│   ├── vault-service.ncl\n│   ├── extension-registry.ncl\n│   ├── rag.ncl\n│   ├── ai-service.ncl\n│   └── provisioning-daemon.ncl\n├── defaults/\n│   ├── vault-service-defaults.ncl\n│   ├── extension-registry-defaults.ncl\n│   ├── rag-defaults.ncl\n│   ├── ai-service-defaults.ncl\n│   ├── provisioning-daemon-defaults.ncl\n│   └── deployment/\n│       ├── solo-defaults.ncl\n│       ├── multiuser-defaults.ncl\n│       ├── cicd-defaults.ncl\n│       └── enterprise-defaults.ncl\n├── validators/\n├── templates/\n├── constraints/\n└── values/\n```\n\n**Using Pre-Generated Configurations**:\n\nAll 5 new services come with pre-built TOML configs for each deployment mode:\n\n```\n# View available schemas for vault service\nls -la provisioning/schemas/platform/schemas/vault-service.ncl\nls -la provisioning/schemas/platform/defaults/vault-service-defaults.ncl\n\n# Load enterprise mode\nexport VAULT_MODE=enterprise\ncargo run -p vault-service\n\n# Or load multiuser mode\nexport REGISTRY_MODE=multiuser\ncargo run -p extension-registry\n\n# All 5 services support mode-based loading\nexport RAG_MODE=cicd\nexport AI_SERVICE_MODE=enterprise\nexport DAEMON_MODE=multiuser\n```\n\n## Updating Configuration\n\n### Change a Setting\n\n1. **Edit source config**: `vim workspace_librecloud/config/config.ncl`\n2. **Validate changes**: `nickel typecheck workspace_librecloud/config/config.ncl`\n3. **Re-export to TOML**: `provisioning config export`\n4. **Restart affected service** (if needed): `provisioning restart orchestrator`\n\n### Using TypeDialog to Update\n\nIf you prefer interactive updating:\n\n```\n# Re-run TypeDialog form (overwrites config.ncl)\nprovisioning config platform orchestrator\n\n# Or edit via TypeDialog with existing values\ntypedialog form .typedialog/provisioning/platform/orchestrator/form.toml\n```\n\n## Troubleshooting\n\n### Form Won't Load\n\n**Problem**: `Failed to parse config file`\n\n**Solution**: Check form.toml syntax and verify required fields are present (name, description, locales_path, templates_path)\n\n```\nhead -10 .typedialog/provisioning/platform/orchestrator/form.toml\n```\n\n### Validation Fails\n\n**Problem**: `Nickel configuration validation failed`\n\n**Solution**: Check for syntax errors and correct field names\n\n```\nnickel typecheck workspace_librecloud/config/config.ncl 2>&1 | less\n```\n\nCommon issues: Missing closing braces, incorrect field names, wrong data types\n\n### Export Creates Empty Files\n\n**Problem**: Generated TOML files are empty\n\n**Solution**: Verify config.ncl exports to JSON and check all required sections exist\n\n```\nnickel export --format json workspace_librecloud/config/config.ncl | head -20\n```\n\n### Services Don't Use New Config\n\n**Problem**: Changes don't take effect\n\n**Solution**:\n\n1. Verify export succeeded: `ls -lah workspace_librecloud/config/generated/platform/`\n2. Check service path: `provisioning start orchestrator --check`\n3. Restart service: `provisioning restart orchestrator`\n\n## Configuration Examples\n\n### Development Setup\n\n```\n{\n  workspace = {\n    name = "dev",\n    path = "/Users/dev/workspace",\n    description = "Development workspace"\n  },\n\n  providers = {\n    local = {\n      enabled = true,\n      base_path = "/opt/vms"\n    },\n    upcloud = { enabled = false },\n    aws = { enabled = false }\n  },\n\n  platform = {\n    orchestrator = {\n      enabled = true,\n      server = { host = "127.0.0.1", port = 9090 },\n      storage = { type = "filesystem" },\n      logging = { level = "debug", format = "json" }\n    },\n    kms = {\n      enabled = true,\n      backend = "age"\n    }\n  }\n}\n```\n\n### Production Setup\n\n```\n{\n  workspace = {\n    name = "prod",\n    path = "/opt/provisioning/prod",\n    description = "Production workspace"\n  },\n\n  providers = {\n    upcloud = {\n      enabled = true,\n      api_user = "{{env.UPCLOUD_USER}}",\n      api_password = "{{kms.decrypt('upcloud_prod')}}",\n      default_zone = "de-fra1"\n    },\n    aws = { enabled = false },\n    local = { enabled = false }\n  },\n\n  platform = {\n    orchestrator = {\n      enabled = true,\n      server = { host = "0.0.0.0", port = 9090, workers = 8 },\n      storage = {\n        type = "surrealdb-server",\n        url = "ws://surreal.internal:8000"\n      },\n      monitoring = {\n        enabled = true,\n        metrics_interval_seconds = 30\n      },\n      logging = { level = "info", format = "json" }\n    },\n    kms = {\n      enabled = true,\n      backend = "vault",\n      url = "https://vault.internal:8200"\n    }\n  }\n}\n```\n\n### Multi-Provider Setup\n\n```\n{\n  workspace = {\n    name = "multi",\n    path = "/opt/multi",\n    description = "Multi-cloud workspace"\n  },\n\n  providers = {\n    upcloud = {\n      enabled = true,\n      api_user = "{{env.UPCLOUD_USER}}",\n      default_zone = "de-fra1",\n      zones = ["de-fra1", "us-nyc1", "nl-ams1"]\n    },\n    aws = {\n      enabled = true,\n      access_key = "{{env.AWS_ACCESS_KEY_ID}}"\n    },\n    local = {\n      enabled = true,\n      base_path = "/opt/local-vms"\n    }\n  },\n\n  platform = {\n    orchestrator = {\n      enabled = true,\n      multi_workspace = false,\n      storage = { type = "filesystem" }\n    },\n    kms = {\n      enabled = true,\n      backend = "rustyvault"\n    }\n  }\n}\n```\n\n## Best Practices\n\n### 1. Use TypeDialog for Initial Setup\n\nStart with TypeDialog forms for the best experience:\n\n```\nprovisioning config platform orchestrator\n```\n\n### 2. Never Edit Generated Files\n\nOnly edit the source `.ncl` file, not the generated TOML files.\n\n**Correct**: `vim workspace_librecloud/config/config.ncl`\n\n**Wrong**: `vim workspace_librecloud/config/generated/platform/orchestrator.toml`\n\n### 3. Validate Before Deploy\n\nAlways validate before deploying changes:\n\n```\nnickel typecheck workspace_librecloud/config/config.ncl\nprovisioning config export\n```\n\n### 4. Use Environment Variables for Secrets\n\nNever hardcode credentials in config. Reference environment variables or KMS:\n\n**Wrong**: `api_password = "my-password"`\n\n**Correct**: `api_password = "{{env.UPCLOUD_PASSWORD}}"`\n\n**Better**: `api_password = "{{kms.decrypt('upcloud_key')}}"`\n\n### 5. Document Changes\n\nAdd comments explaining custom settings in the Nickel file.\n\n## Related Documentation\n\n### Core Resources\n- **Configuration System**: See `CLAUDE.md#configuration-file-format-selection`\n- **Migration Guide**: See `provisioning/config/README.md#migration-strategy`\n- **Schema Reference**: See `provisioning/schemas/`\n- **Nickel Language**: See ADR-011 in `docs/architecture/adr/`\n\n### Platform Services\n- **Platform Services Overview**: See `provisioning/platform/*/README.md`\n- **Core Services** (Phases 8-12): orchestrator, control-center, mcp-server\n- **New Services** (Phases 13-19):\n  - vault-service: Secrets management and encryption\n  - extension-registry: Extension distribution via Gitea/OCI\n  - rag: Retrieval-Augmented Generation system\n  - ai-service: AI model integration with DAG workflows\n  - provisioning-daemon: Background provisioning operations\n\n**Note**: Installer is a distribution tool (provisioning/tools/distribution/create-installer.nu), not a platform service configurable via TypeDialog.\n\n### Public Definition Locations\n- **TypeDialog Forms** (Interactive UI): `provisioning/.typedialog/platform/forms/`\n- **Nickel Schemas** (Type Definitions): `provisioning/schemas/platform/schemas/`\n- **Default Values** (Base Configuration): `provisioning/schemas/platform/defaults/`\n- **Validators** (Business Logic): `provisioning/schemas/platform/validators/`\n- **Deployment Modes** (Presets): `provisioning/schemas/platform/defaults/deployment/`\n- **Rust Integration**: `provisioning/platform/crates/*/src/config.rs`\n\n## Getting Help\n\n### Validation Errors\n\nGet detailed error messages and check available fields:\n\n```\nnickel typecheck workspace_librecloud/config/config.ncl 2>&1 | less\ngrep "prompt =" .typedialog/provisioning/platform/orchestrator/form.toml\n```\n\n### Configuration Questions\n\n```\n# Show all available config commands\nprovisioning config --help\n\n# Show help for specific service\nprovisioning config platform --help\n\n# List providers and services\nprovisioning config providers list\nprovisioning config services list\n```\n\n### Test Configuration\n\n```\n# Validate without deploying\nnickel typecheck workspace_librecloud/config/config.ncl\n\n# Export to see generated config\nprovisioning config export\n\n# Check generated files\nls -la workspace_librecloud/config/generated/\n```
