# Platform Services Configuration Setup Script\n\n**Path**: `provisioning/scripts/setup-platform-config.sh`\n\nSetup and manage platform service configurations in `provisioning/config/runtime/`.\n\n## Features\n\n- ✅ **Interactive Mode**: Guided setup with TypeDialog or quick mode\n- ✅ **Interactive TypeDialog**: Web/TUI/CLI form-based configuration\n- ✅ **Quick Mode**: Auto-setup from defaults + mode overlays\n- ✅ **Automatic TOML Export**: Generates TOML files for Rust services\n- ✅ **Runtime Detection**: Detect existing configs and offer update/replace options\n- ✅ **Batch Operations**: Configure all 8 services at once\n- ✅ **Cleanup Management**: Remove/reset configurations safely\n\n## Usage\n\n### Interactive Setup (Recommended)\n\n```\n# Start interactive wizard\n./provisioning/scripts/setup-platform-config.sh\n\n# Prompts for:\n# 1. Action: TypeDialog, Quick Mode, Clean, or List\n# 2. Service (if TypeDialog/Quick)\n# 3. Mode (solo/multiuser/cicd/enterprise)\n# 4. Backend (web/tui/cli, if TypeDialog)\n```\n\n### Command-Line Options\n\n```\n# Configure specific service via TypeDialog\n./provisioning/scripts/setup-platform-config.sh \\n  --service orchestrator \\n  --mode solo \\n  --backend web\n\n# Quick setup all services for enterprise mode\n./provisioning/scripts/setup-platform-config.sh \\n  --quick-mode \\n  --mode enterprise\n\n# Regenerate TOML files from existing .ncl configs\n./provisioning/scripts/setup-platform-config.sh \\n  --generate-toml\n\n# List available options\n./provisioning/scripts/setup-platform-config.sh --list-modes\n./provisioning/scripts/setup-platform-config.sh --list-services\n./provisioning/scripts/setup-platform-config.sh --list-configs\n\n# Clean all runtime configurations\n./provisioning/scripts/setup-platform-config.sh --clean\n```\n\n## Workflow\n\n### 1. Initial Setup (Empty Runtime)\n\n```\nInteractive Prompt\n  ↓\n├─ TypeDialog (Recommended)\n│  ├─ Load form definitions\n│  ├─ User fills form (web/tui/cli)\n│  └─ Generates orchestrator.solo.ncl\n│     ↓\n│     Auto-export to orchestrator.solo.toml\n│\n└─ Quick Mode\n   ├─ Select mode (solo/multiuser/cicd/enterprise)\n   ├─ Compose all services: defaults + mode overlay\n   ├─ Create 8 .ncl files\n   └─ Auto-export to 8 .toml files\n```\n\n### 2. Update Existing Configuration\n\n```\nDetect Existing Config\n  ↓\nChoose Action:\n  ├─ Clean up & start fresh\n  ├─ Update via TypeDialog (edit existing)\n  ├─ Use quick mode (regenerate)\n  └─ List current configs\n```\n\n### 3. Manual NCL Edits\n\n```\nUser edits: provisioning/config/runtime/orchestrator.solo.ncl\n  ↓\nRun: ./setup-platform-config.sh --generate-toml\n  ↓\nAuto-exports to: provisioning/config/runtime/generated/orchestrator.solo.toml\n  ↓\nService loads TOML automatically\n```\n\n## Configuration Layers\n\nThe script composes configurations from multiple layers:\n\n```\n1. Schema (TYPE-SAFE CONTRACT)\n   ↓\n   provisioning/schemas/platform/schemas/orchestrator.ncl\n   (Defines valid fields, types, constraints)\n\n2. Service Defaults (BASE VALUES)\n   ↓\n   provisioning/schemas/platform/defaults/orchestrator-defaults.ncl\n   (Default values for all orchestrator settings)\n\n3. Mode Overlay (MODE-SPECIFIC TUNING)\n   ↓\n   provisioning/schemas/platform/defaults/deployment/solo-defaults.ncl\n   (Resource limits for solo mode: 2 CPU, 4GB RAM)\n\n4. Composition (MERGE)\n   ↓\n   defaults.merge_config_with_mode(mode_config)\n   (Merges base + mode overlay)\n\n5. Runtime Config (USER CUSTOMIZATION)\n   ↓\n   provisioning/config/runtime/orchestrator.solo.ncl\n   (Final config, can be hand-edited)\n\n6. TOML Export (SERVICE CONSUMPTION)\n   ↓\n   provisioning/config/runtime/generated/orchestrator.solo.toml\n   (Rust service reads this)\n```\n\n## Services & Modes\n\n### 8 Available Services\n\n```\n1. orchestrator         - Main orchestration engine\n2. control-center       - Web UI and management console\n3. mcp-server           - Model Context Protocol server\n4. vault-service        - Secrets management and encryption\n5. extension-registry   - Extension distribution system\n6. rag                  - Retrieval-Augmented Generation\n7. ai-service           - AI model integration\n8. provisioning-daemon  - Background operations\n```\n\n### 4 Deployment Modes\n\n| Mode | Specs | Use Case |\n| ------ | ------- | ---------- |\n| `solo` | 2 CPU, 4GB RAM | Development, testing |\n| `multiuser` | 4 CPU, 8GB RAM | Team staging |\n| `cicd` | 8 CPU, 16GB RAM | CI/CD pipelines |\n| `enterprise` | 16+ CPU, 32+ GB | Production HA |\n\n## Directory Structure\n\n```\nprovisioning/\n├── config/\n│   └── runtime/                    # 🔒 PRIVATE (gitignored)\n│       ├── .gitignore\n│       ├── orchestrator.solo.ncl         # Runtime config (user editable)\n│       ├── vault-service.multiuser.ncl   # Runtime config\n│       └── generated/                    # TOMLs (auto-generated)\n│           ├── orchestrator.solo.toml         # For Rust services\n│           └── vault-service.multiuser.toml\n│\n├── schemas/platform/               # 📘 PUBLIC (versionable)\n│   ├── schemas/                    # Type contracts\n│   ├── defaults/                   # Base values\n│   │   ├── orchestrator-defaults.ncl\n│   │   └── deployment/\n│   │       ├── solo-defaults.ncl\n│   │       ├── multiuser-defaults.ncl\n│   │       ├── cicd-defaults.ncl\n│   │       └── enterprise-defaults.ncl\n│   └── validators/                 # Business logic\n│\n└── scripts/\n    └── setup-platform-config.sh    # This script\n```\n\n## Requirements\n\n- **Bash 4.0+**\n- **Nickel 0.10+** - Configuration language\n- **Nushell 0.109+** - Script engine\n- **TypeDialog** (optional, for interactive setup)\n\n## Integration with Provisioning Installer\n\n### ⚠️ Current Status: Installer NOT YET IMPLEMENTED\n\nThe `setup-platform-config.sh` script is a **standalone tool** ready to use independently.\n\n**For now**: Call the script manually before running services\n\n```\n# Step 1: Setup platform configurations (MANUAL)\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo\n\n# Step 2: Run services\nexport ORCHESTRATOR_MODE=solo\ncargo run -p orchestrator\n```\n\n### Future: When Installer is Implemented\n\nOnce `provisioning/scripts/install.sh` is ready, it will look like:\n\n```\n#!/bin/bash\n# provisioning/scripts/install.sh (FUTURE)\n\n# Pre-flight checks\ncheck_dependencies() {\n    command -v nickel >/dev/null || { echo "Nickel required"; exit 1; }\n    command -v nu >/dev/null || { echo "Nushell required"; exit 1; }\n}\ncheck_dependencies\n\n# Install provisioning system\necho "Installing provisioning system..."\n# (implementation here)\n\n# Setup platform configurations\necho "Setting up platform configurations..."\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo\n\n# Build and verify\necho "Building platform services..."\ncargo build -p orchestrator -p control-center -p mcp-server\n\necho "Installation complete!"\n```\n\n### CI/CD Integration (Available Now)\n\nFor CI/CD pipelines that don't require the full installer:\n\n```\n#!/bin/bash\n# ci/setup.sh\n\n# Setup configurations for CI/CD mode\n./provisioning/scripts/setup-platform-config.sh \\n  --quick-mode \\n  --mode cicd\n\n# Run tests\ncargo test --all\n\n# Deploy\ndocker-compose -f provisioning/platform/infrastructure/docker/docker-compose.cicd.yml up\n```\n\n## Important Notes\n\n### ⚠️ Manual Edits\n\nIf you manually edit `.ncl` files in `provisioning/config/runtime/`:\n\n```\n# Always regenerate TOMLs afterward\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n```\n\n### 🔒 Private Configurations\n\nFiles in `provisioning/config/runtime/` are **gitignored**:\n- `.ncl` files (may contain secrets/encrypted values)\n- `generated/*.toml` files (auto-generated, no need to version)\n\n### 📘 Public Schemas\n\nSchemas in `provisioning/schemas/platform/` are **public**:\n- Source of truth for configuration structure\n- Versionable and shared across team\n- Can be committed to git\n\n### 🔄 Regeneration\n\nThe script is **idempotent** - run it multiple times safely:\n\n```\n# Safe: Re-runs setup, updates configs\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode multiuser\n\n# Does NOT overwrite manually edited files (unless --clean is used)\n```\n\n## Troubleshooting\n\n### Nickel Validation Fails\n\n```\n# Check syntax of generated config\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# View detailed error\nnickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl\n```\n\n### TOML Export Fails\n\n```\n# Check if Nickel config is valid\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# Try manual export\nnickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl\n```\n\n### Service Won't Start\n\n```\n# Verify TOML exists\nls -la provisioning/config/runtime/generated/orchestrator.solo.toml\n\n# Check TOML syntax\ncat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20\n\n# Verify service can read TOML\nORCHESTRATOR_MODE=solo cargo run -p orchestrator --\n```\n\n## Examples\n\n### Example 1: Quick Setup for Development\n\n```\n# Setup all services for solo mode (2 CPU, 4GB RAM)\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo\n\n# Result:\n# ✓ Created provisioning/config/runtime/orchestrator.solo.ncl\n# ✓ Created provisioning/config/runtime/control-center.solo.ncl\n# ✓ ... (8 services total)\n# ✓ Generated 8 TOML files in provisioning/config/runtime/generated/\n\n# Run service:\nexport ORCHESTRATOR_MODE=solo\ncargo run -p orchestrator\n```\n\n### Example 2: Interactive TypeDialog Setup\n\n```\n# Configure orchestrator in multiuser mode with web UI\n./provisioning/scripts/setup-platform-config.sh \\n  --service orchestrator \\n  --mode multiuser \\n  --backend web\n\n# TypeDialog opens browser, user fills form\n# Result:\n# ✓ Created provisioning/config/runtime/orchestrator.multiuser.ncl\n# ✓ Generated provisioning/config/runtime/generated/orchestrator.multiuser.toml\n\n# Run service:\nexport ORCHESTRATOR_MODE=multiuser\ncargo run -p orchestrator\n```\n\n### Example 3: Update After Manual Edit\n\n```\n# Edit config manually\nvim provisioning/config/runtime/orchestrator.solo.ncl\n\n# Regenerate TOML (critical!)\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n\n# Verify changes\ncat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20\n\n# Restart service with new config\npkill orchestrator\nORCHESTRATOR_MODE=solo cargo run -p orchestrator\n```\n\n## Performance Notes\n\n- **Quick Mode**: ~1-2 seconds (no user interaction, direct composition)\n- **TypeDialog (web)**: 10-30 seconds (server startup + UI loading)\n- **TOML Export**: <1 second per service\n- **Full Setup**: 5-10 minutes (8 services via TypeDialog)\n\n---\n\n**Version**: 1.0.0\n**Created**: 2026-01-05\n**Last Updated**: 2026-01-05