<p align="center">\n  <img src="resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>\n</p>\n<p align="center">\n  <img src="resources/logo-text.svg" alt="Provisioning" width="500"/>\n</p>\n\n# Provisioning - Infrastructure Automation Platform\n\n> **A modular, declarative Infrastructure as Code (IaC) platform for managing complete infrastructure lifecycles**\n\n## Table of Contents\n\n- [What is Provisioning?](#what-is-provisioning)\n- [Why Provisioning?](#why-provisioning)\n- [Core Concepts](#core-concepts)\n- [Architecture](#architecture)\n- [Key Features](#key-features)\n- [Technology Stack](#technology-stack)\n- [How It Works](#how-it-works)\n- [Use Cases](#use-cases)\n- [Getting Started](#getting-started)\n\n---\n\n## What is Provisioning?\n\n**Provisioning** is a comprehensive **Infrastructure as Code (IaC)** platform designed to manage\ncomplete infrastructure lifecycles: cloud providers, infrastructure services, clusters,\nand isolated workspaces across multiple cloud/local environments.\n\nExtensible and customizable by design, it delivers type-safe, configuration-driven workflows\nwith enterprise security (encrypted configuration, Cosmian KMS integration, Cedar policy engine,\nsecrets management, authorization and permissions control, compliance checking, anomaly detection)\nand adaptable deployment modes (interactive UI, CLI automation, unattended CI/CD)\nsuitable for any scale from development to production.\n\n### Technical Definition\n\nDeclarative Infrastructure as Code (IaC) platform providing:\n\n- **Type-safe, configuration-driven workflows** with schema validation and constraint checking\n- **Modular, extensible architecture**: cloud providers, task services, clusters, workspaces\n- **Multi-cloud abstraction layer** with unified API (UpCloud, AWS, local infrastructure)\n- **High-performance state management**:\n  - Graph database backend for complex relationships\n  - Real-time state tracking and queries\n  - Multi-model data storage (document, graph, relational)\n- **Enterprise security stack**:\n  - Encrypted configuration and secrets management\n  - Cosmian KMS integration for confidential key management\n  - Cedar policy engine for fine-grained access control\n  - Authorization and permissions control via platform services\n  - Compliance checking and policy enforcement\n  - Anomaly detection for security monitoring\n  - Audit logging and compliance tracking\n- **Hybrid orchestration**: Rust-based performance layer + scripting flexibility\n- **Production-ready features**:\n  - Batch workflows with dependency resolution\n  - Checkpoint recovery and automatic rollback\n  - Parallel execution with state management\n- **Adaptable deployment modes**:\n  - Interactive TUI for guided setup\n  - Headless CLI for scripted automation\n  - Unattended mode for CI/CD pipelines\n- **Hierarchical configuration system** with inheritance and overrides\n\n### What It Does\n\n- **Provisions Infrastructure** - Create servers, networks, storage across multiple cloud providers\n- **Installs Services** - Deploy Kubernetes, containerd, databases, monitoring, and 50+ infrastructure components\n- **Manages Clusters** - Orchestrate complete cluster deployments with dependency management\n- **Handles Configuration** - Hierarchical configuration system with inheritance and overrides\n- **Orchestrates Workflows** - Batch operations with parallel execution and checkpoint recovery\n- **Manages Secrets** - SOPS/Age integration for encrypted configuration\n- **Secures Infrastructure** - Enterprise security with JWT, MFA, Cedar policies, audit logging\n- **Optimizes Performance** - Native plugins providing 10-50x speed improvements\n\n---\n\n## Why Provisioning?\n\n### The Problems It Solves\n\n#### 1. **Multi-Cloud Complexity**\n\n**Problem**: Each cloud provider has different APIs, tools, and workflows.\n\n**Solution**: Unified abstraction layer with provider-agnostic interfaces. Write configuration once, deploy anywhere using Nickel schemas.\n\n```\n# Same configuration works on UpCloud, AWS, or local infrastructure\n{\n  servers = [\n    {\n      name = "web-01"\n      plan = "medium"      # Abstract size, provider-specific translation\n      provider = "upcloud" # Switch to "aws" or "local" as needed\n    }\n  ]\n}\n```\n\n#### 2. **Dependency Hell**\n\n**Problem**: Infrastructure components have complex dependencies (Kubernetes needs containerd, Cilium needs Kubernetes, etc.).\n\n**Solution**: Automatic dependency resolution with topological sorting and health checks via Nickel schemas.\n\n```\n# Provisioning resolves: containerd → etcd → kubernetes → cilium\n{\n  taskservs = ["cilium"]  # Automatically installs all dependencies\n}\n```\n\n#### 3. **Configuration Sprawl**\n\n**Problem**: Environment variables, hardcoded values, scattered configuration files.\n\n**Solution**: Hierarchical configuration system with 476+ config accessors replacing 200+ ENV variables.\n\n```\nDefaults → User → Project → Infrastructure → Environment → Runtime\n```\n\n#### 4. **Imperative Scripts**\n\n**Problem**: Brittle shell scripts that don't handle failures, don't support rollback, hard to maintain.\n\n**Solution**: Declarative Nickel configurations with validation, type safety, lazy evaluation, and automatic rollback.\n\n#### 5. **Lack of Visibility**\n\n**Problem**: No insight into what's happening during deployment, hard to debug failures.\n\n**Solution**:\n\n- Real-time workflow monitoring\n- Comprehensive logging system\n- Web-based control center\n- REST API for integration\n\n#### 6. **No Standardization**\n\n**Problem**: Each team builds their own deployment tools, no shared patterns.\n\n**Solution**: Reusable task services, cluster templates, and workflow patterns.\n\n---\n\n## Core Concepts\n\n### 1. **Providers**\n\nCloud infrastructure backends that handle resource provisioning.\n\n- **UpCloud** - Primary cloud provider\n- **AWS** - Amazon Web Services integration\n- **Local** - Local infrastructure (VMs, Docker, bare metal)\n\nProviders implement a common interface, making infrastructure code portable.\n\n### 2. **Task Services (TaskServs)**\n\nReusable infrastructure components that can be installed on servers.\n\n**Categories**:\n\n- **Container Runtimes** - containerd, Docker, Podman, crun, runc, youki\n- **Orchestration** - Kubernetes, etcd, CoreDNS\n- **Networking** - Cilium, Flannel, Calico, ip-aliases\n- **Storage** - Rook-Ceph, local storage\n- **Databases** - PostgreSQL, Redis, SurrealDB\n- **Observability** - Prometheus, Grafana, Loki\n- **Security** - Webhook, KMS, Vault\n- **Development** - Gitea, Radicle, ORAS\n\nEach task service includes:\n\n- Version management\n- Dependency declarations\n- Health checks\n- Installation/uninstallation logic\n- Configuration schemas\n\n### 3. **Clusters**\n\nComplete infrastructure deployments combining servers and task services.\n\n**Examples**:\n\n- **Kubernetes Cluster** - HA control plane + worker nodes + CNI + storage\n- **Database Cluster** - Replicated PostgreSQL with backup\n- **Build Infrastructure** - BuildKit + container registry + CI/CD\n\nClusters handle:\n\n- Multi-node coordination\n- Service distribution\n- High availability\n- Rolling updates\n\n### 4. **Workspaces**\n\nIsolated environments for different projects or deployment stages.\n\n```\nworkspace_librecloud/     # Production workspace\n├── infra/                # Infrastructure definitions\n├── config/               # Workspace configuration\n├── extensions/           # Custom modules\n└── runtime/              # State and runtime data\n\nworkspace_dev/            # Development workspace\n├── infra/\n└── config/\n```\n\nSwitch between workspaces with single command:\n\n```\nprovisioning workspace switch librecloud\n```\n\n### 5. **Workflows**\n\nCoordinated sequences of operations with dependency management.\n\n**Types**:\n\n- **Server Workflows** - Create/delete/update servers\n- **TaskServ Workflows** - Install/remove infrastructure services\n- **Cluster Workflows** - Deploy/scale complete clusters\n- **Batch Workflows** - Multi-cloud parallel operations\n\n**Features**:\n\n- Dependency resolution\n- Parallel execution\n- Checkpoint recovery\n- Automatic rollback\n- Progress monitoring\n\n---\n\n## Architecture\n\n### System Components\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                     User Interface Layer                        │\n│  • CLI (provisioning command)                                   │\n│  • Web Control Center (UI)                                      │\n│  • REST API                                                     │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                     Core Engine Layer                           │\n│  • Command Routing & Dispatch                                   │\n│  • Configuration Management                                     │\n│  • Provider Abstraction                                         │\n│  • Utility Libraries                                            │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                   Orchestration Layer                           │\n│  • Workflow Orchestrator (Rust/Nushell hybrid)                  │\n│  • Dependency Resolver                                          │\n│  • State Manager                                                │\n│  • Task Scheduler                                               │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                    Extension Layer                              │\n│  • Providers (Cloud APIs)                                       │\n│  • Task Services (Infrastructure Components)                    │\n│  • Clusters (Complete Deployments)                              │\n│  • Workflows (Automation Templates)                             │\n└─────────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────────┐\n│                  Infrastructure Layer                           │\n│  • Cloud Resources (Servers, Networks, Storage)                 │\n│  • Kubernetes Clusters                                          │\n│  • Running Services                                             │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Directory Structure\n\n```\nproject-provisioning/\n├── provisioning/              # Core provisioning system\n│   ├── core/                  # Core engine and libraries\n│   │   ├── cli/               # Command-line interface\n│   │   ├── nulib/             # Core Nushell libraries\n│   │   ├── plugins/           # System plugins (Rust native)\n│   │   └── scripts/           # Utility scripts\n│   │\n│   ├── extensions/            # Extensible components\n│   │   ├── providers/         # Cloud provider implementations\n│   │   ├── taskservs/         # Infrastructure service definitions\n│   │   ├── clusters/          # Complete cluster configurations\n│   │   └── workflows/         # Core workflow templates\n│   │\n│   ├── platform/              # Platform services\n│   │   ├── orchestrator/      # Rust orchestrator service\n│   │   ├── control-center/    # Web control center\n│   │   ├── mcp-server/        # Model Context Protocol server\n│   │   ├── api-gateway/       # REST API gateway\n│   │   ├── oci-registry/      # OCI registry for extensions\n│   │   └── installer/         # Platform installer (TUI + CLI)\n│   │\n│   ├── schemas/               # Nickel schema definitions (PRIMARY IaC)\n│   │   ├── main.ncl           # Main infrastructure schema\n│   │   ├── providers/         # Provider-specific schemas\n│   │   ├── infrastructure/    # Infra definitions\n│   │   ├── deployment/        # Deployment schemas\n│   │   ├── services/          # Service schemas\n│   │   ├── operations/        # Operations schemas\n│   │   └── generator/         # Runtime schema generation\n│   │\n│   ├── docs/                  # Product documentation (mdBook)\n│   ├── config/                # Configuration examples\n│   ├── tools/                 # Build and distribution tools\n│   └── justfiles/             # Just recipes for common tasks\n│\n├── workspace/                 # User workspaces and data\n│   ├── infra/                 # Infrastructure definitions\n│   ├── config/                # User configuration\n│   ├── extensions/            # User extensions\n│   └── runtime/               # Runtime data and state\n│\n├── docs/                      # Architecture & Development docs\n│   ├── architecture/          # System design and ADRs\n│   └── development/           # Development guidelines\n│\n└── .github/                   # CI/CD workflows\n    └── workflows/             # GitHub Actions (Rust, Nickel, Nushell)\n```\n\n### Platform Services\n\n#### 1. **Orchestrator** (`platform/orchestrator/`)\n\n- **Language**: Rust + Nushell\n- **Purpose**: Workflow execution, task scheduling, state management\n- **Features**:\n  - File-based persistence\n  - Priority processing\n  - Retry logic with exponential backoff\n  - Checkpoint-based recovery\n  - REST API endpoints\n\n#### 2. **Control Center** (`platform/control-center/`)\n\n- **Language**: Web UI + Backend API\n- **Purpose**: Web-based infrastructure management\n- **Features**:\n  - Dashboard views\n  - Real-time monitoring\n  - Interactive deployments\n  - Log viewing\n\n#### 3. **MCP Server** (`platform/mcp-server/`)\n\n- **Language**: Nushell\n- **Purpose**: Model Context Protocol integration for AI assistance\n- **Features**:\n  - 7 AI-powered settings tools\n  - Intelligent config completion\n  - Natural language infrastructure queries\n\n#### 4. **OCI Registry** (`platform/oci-registry/`)\n\n- **Purpose**: Extension distribution and versioning\n- **Features**:\n  - Task service packages\n  - Provider packages\n  - Cluster templates\n  - Workflow definitions\n\n#### 5. **Installer** (`platform/installer/`)\n\n- **Language**: Rust (Ratatui TUI) + Nushell\n- **Purpose**: Platform installation and setup\n- **Features**:\n  - Interactive TUI mode\n  - Headless CLI mode\n  - Unattended CI/CD mode\n  - Configuration generation\n\n---\n\n## Key Features\n\n### 1. **Modular CLI Architecture** (v3.2.0)\n\n84% code reduction with domain-driven design.\n\n- **Main CLI**: 211 lines (from 1,329 lines)\n- **80+ shortcuts**: `s` → `server`, `t` → `taskserv`, etc.\n- **Bi-directional help**: `provisioning help ws` = `provisioning ws help`\n- **7 domain modules**: infrastructure, orchestration, development, workspace, configuration, utilities, generation\n\n### 2. **Configuration System** (v2.0.0)\n\nHierarchical, config-driven architecture.\n\n- **476+ config accessors** replacing 200+ ENV variables\n- **Hierarchical loading**: defaults → user → project → infra → env → runtime\n- **Variable interpolation**: `{{paths.base}}`, `{{env.HOME}}`, `{{now.date}}`\n- **Multi-format support**: TOML, YAML, KCL\n\n### 3. **Batch Workflow System** (v3.1.0)\n\nProvider-agnostic batch operations with 85-90% token efficiency.\n\n- **Multi-cloud support**: Mixed UpCloud + AWS + local in single workflow\n- **KCL schema integration**: Type-safe workflow definitions\n- **Dependency resolution**: Topological sorting with soft/hard dependencies\n- **State management**: Checkpoint-based recovery with rollback\n- **Real-time monitoring**: Live progress tracking\n\n### 4. **Hybrid Orchestrator** (v3.0.0)\n\nRust/Nushell architecture solving deep call stack limitations.\n\n- **High-performance coordination layer**\n- **File-based persistence**\n- **Priority processing with retry logic**\n- **REST API for external integration**\n- **Comprehensive workflow system**\n\n### 5. **Workspace Switching** (v2.0.5)\n\nCentralized workspace management.\n\n- **Single-command switching**: `provisioning workspace switch <name>`\n- **Automatic tracking**: Last-used timestamps, active workspace markers\n- **User preferences**: Global settings across all workspaces\n- **Workspace registry**: Centralized configuration in `user_config.yaml`\n\n### 6. **Interactive Guides** (v3.3.0)\n\nStep-by-step walkthroughs and quick references.\n\n- **Quick reference**: `provisioning sc` (fastest)\n- **Complete guides**: from-scratch, update, customize\n- **Copy-paste ready**: All commands include placeholders\n- **Beautiful rendering**: Uses glow, bat, or less\n\n### 7. **Test Environment Service** (v3.4.0)\n\nAutomated container-based testing.\n\n- **Three test types**: Single taskserv, server simulation, multi-node clusters\n- **Topology templates**: Kubernetes HA, etcd clusters, etc.\n- **Auto-cleanup**: Optional automatic cleanup after tests\n- **CI/CD integration**: Easy integration into pipelines\n\n### 8. **Platform Installer** (v3.5.0)\n\nMulti-mode installation system with TUI, CLI, and unattended modes.\n\n- **Interactive TUI**: Beautiful Ratatui terminal UI with 7 screens\n- **Headless Mode**: CLI automation for scripted installations\n- **Unattended Mode**: Zero-interaction CI/CD deployments\n- **Deployment Modes**: Solo (2 CPU/4GB), MultiUser (4 CPU/8GB), CICD (8 CPU/16GB), Enterprise (16 CPU/32GB)\n- **MCP Integration**: 7 AI-powered settings tools for intelligent configuration\n\n### 9. **Version Management System** (v3.6.0)\n\nCentralized tool and provider version management with bash-compatible export.\n\n- **Unified Version Source**: All versions defined in Nickel files (`versions.ncl` and provider `version.ncl`)\n- **Generated Versions File**: Bash-compatible KEY="VALUE" format for shell scripts\n- **Core Tools**: NUSHELL, NICKEL, SOPS, AGE, K9S with convenient aliases (NU for NUSHELL)\n- **Provider Versions**: Automatically discovers and includes all provider versions (AWS, HCLOUD, UPCTL, etc.)\n- **Command**: `provisioning setup versions` generates `/provisioning/core/versions` file\n- **Shell Integration**: Can be sourced directly in bash scripts: `source /provisioning/core/versions && echo $NU_VERSION`\n- **Usage**:\n    ```bash\n    # Generate versions file\n    provisioning setup versions\n\n    # Use in bash scripts\n    source /provisioning/core/versions\n    echo "Using Nushell version: $NU_VERSION"\n    echo "AWS CLI version: $PROVIDER_AWS_VERSION"\n    ```\n\n### 10. **Nushell Plugins Integration** (v1.0.0)\n\nThree native Rust plugins providing 10-50x performance improvements over HTTP API.\n\n- **Three Native Plugins**: auth, KMS, orchestrator\n- **Performance Gains**:\n  - KMS operations: ~5ms vs ~50ms (10x faster)\n  - Orchestrator queries: ~1ms vs ~30ms (30x faster)\n  - Auth verification: ~10ms vs ~50ms (5x faster)\n- **OS-Native Keyring**: macOS Keychain, Linux Secret Service, Windows Credential Manager\n- **KMS Backends**: RustyVault, Age, AWS KMS, Vault, Cosmian\n- **Graceful Fallback**: Automatic fallback to HTTP if plugins not installed\n\n### 11. **Complete Security System** (v4.0.0)\n\nEnterprise-grade security with 39,699 lines across 12 components.\n\n- **12 Components**: JWT Auth, Cedar Authorization, MFA (TOTP + WebAuthn), Secrets Management, KMS, Audit Logging, Break-Glass, Compliance, Audit Query, Token Management, Access Control, Encryption\n- **Performance**: <20ms overhead per secure operation\n- **Testing**: 350+ comprehensive test cases\n- **API**: 83+ REST endpoints, 111+ CLI commands\n- **Standards**: GDPR, SOC2, ISO 27001 compliance\n- **Key Features**:\n  - RS256 authentication with Argon2id hashing\n  - Policy-as-code with hot reload\n  - Multi-factor authentication (TOTP + WebAuthn/FIDO2)\n  - Dynamic secrets (AWS STS, SSH keys) with TTL\n  - 5 KMS backends with envelope encryption\n  - 7-year audit retention with 5 export formats\n  - Multi-party break-glass approval\n\n---\n\n## Technology Stack\n\n### Core Technologies\n\n| Technology | Version | Purpose | Why |\n| ------------ | --------- | --------- | ----- |\n| **Nickel** | Latest | PRIMARY - Infrastructure-as-code language | Type-safe schemas, lazy evaluation, LSP support, composable records, gradual validation |\n| **Nushell** | 0.109.0+ | Scripting and task automation | Structured data pipelines, cross-platform, modern built-in parsers (JSON/YAML/TOML) |\n| **Rust** | Latest | Platform services (orchestrator, control-center, installer) | Performance, memory safety, concurrency, reliability |\n| **KCL** | DEPRECATED | Legacy configuration (fully replaced by Nickel) | Migration bridge available; use Nickel for new work |\n\n### Data & State Management\n\n| Technology | Version | Purpose | Features |\n| ------------ | --------- | --------- | ---------- |\n| **SurrealDB** | Latest | High-performance graph database backend | Multi-model (document, graph, relational), real-time queries, distributed architecture, complex relationship tracking |\n\n### Platform Services (Rust-based)\n\n| Service | Purpose | Security Features |\n| --------- | --------- | ------------------- |\n| **Orchestrator** | Workflow execution, task scheduling, state management | File-based persistence, retry logic, checkpoint recovery |\n| **Control Center** | Web-based infrastructure management | **Authorization and permissions control**, RBAC, audit logging |\n| **Installer** | Platform installation (TUI + CLI modes) | Secure configuration generation, validation |\n| **API Gateway** | REST API for external integration | Authentication, rate limiting, request validation |\n| **MCP Server** | AI-powered configuration management | 7 settings tools, intelligent config completion |\n| **OCI Registry** | Extension distribution and versioning | Task services, providers, cluster templates |\n\n### Security & Secrets\n\n| Technology | Version | Purpose | Enterprise Features |\n| ------------ | --------- | --------- | --------------------- |\n| **SOPS** | 3.10.2+ | Secrets management | Encrypted configuration files |\n| **Age** | 1.2.1+ | Encryption | Secure key-based encryption |\n| **Cosmian KMS** | Latest | Key Management System | Confidential computing, secure key storage, cloud-native KMS |\n| **Cedar** | Latest | Policy engine | Fine-grained access control, policy-as-code, compliance checking, anomaly detection |\n| **RustyVault** | Latest | Transit encryption engine | 5ms encryption performance, multiple KMS backends |\n| **JWT** | Latest | Authentication tokens | RS256 signatures, Argon2id password hashing |\n| **Keyring** | Latest | OS-native secure storage | macOS Keychain, Linux Secret Service, Windows Credential Manager |\n\n### Version Management\n\n| Component | Purpose | Format |\n| ----------- | --------- | -------- |\n| **versions.ncl** | Core tool versions (Nickel primary) | Nickel schema |\n| **provider version.ncl** | Provider-specific versions | Nickel schema |\n| **provisioning setup versions** | Version file generator | Nushell command |\n| **versions file** | Bash-compatible exports | KEY="VALUE" format |\n\n**Usage**:\n```\n# Generate versions file from Nickel schemas\nprovisioning setup versions\n\n# Source in shell scripts\nsource /provisioning/core/versions\necho $NU_VERSION $PROVIDER_AWS_VERSION\n```\n\n### Optional Tools\n\n| Tool | Purpose |\n| ------ | --------- |\n| **K9s** | Kubernetes management interface |\n| **nu_plugin_tera** | Nushell plugin for Tera template rendering |\n| **nu_plugin_kcl** | Nushell plugin for KCL integration (CLI required, plugin optional) |\n| **nu_plugin_auth** | Authentication plugin (5x faster auth, OS keyring integration) |\n| **nu_plugin_kms** | KMS encryption plugin (10x faster, 5ms encryption) |\n| **nu_plugin_orchestrator** | Orchestrator plugin (30-50x faster queries) |\n| **glow** | Markdown rendering for interactive guides |\n| **bat** | Syntax highlighting for file viewing and guides |\n\n---\n\n## How It Works\n\n### Data Flow\n\n```\n1. User defines infrastructure in Nickel schemas\n   ↓\n2. Nickel evaluates with type validation and lazy evaluation\n   ↓\n3. CLI loads configuration (hierarchical merging)\n   ↓\n4. Configuration validated against provider schemas\n   ↓\n5. Workflow created with operations\n   ↓\n6. Orchestrator receives workflow\n   ↓\n7. Dependencies resolved (topological sort)\n   ↓\n8. Operations executed in order (parallel where possible)\n   ↓\n9. Providers handle cloud operations\n   ↓\n10. Task services installed on servers\n   ↓\n11. State persisted and monitored\n```\n\n### Example Workflow: Deploy Kubernetes Cluster\n\n**Step 1**: Define infrastructure in Nickel\n\n```\n# schemas/my-cluster.ncl\n{\n  metadata = {\n    name = "my-cluster"\n    provider = "upcloud"\n    environment = "production"\n  }\n\n  infrastructure = {\n    servers = [\n      {name = "control-01", plan = "medium", role = "control"}\n      {name = "worker-01", plan = "large", role = "worker"}\n      {name = "worker-02", plan = "large", role = "worker"}\n    ]\n  }\n\n  services = {\n    taskservs = ["kubernetes", "cilium", "rook-ceph"]\n  }\n}\n```\n\n**Step 2**: Submit to Provisioning\n\n```\nprovisioning server create --infra my-cluster\n```\n\n**Step 3**: Provisioning executes workflow\n\n```\n1. Create workflow: "deploy-my-cluster"\n2. Resolve dependencies:\n   - containerd (required by kubernetes)\n   - etcd (required by kubernetes)\n   - kubernetes (explicitly requested)\n   - cilium (explicitly requested, requires kubernetes)\n   - rook-ceph (explicitly requested, requires kubernetes)\n\n3. Execution order:\n   a. Provision servers (parallel)\n   b. Install containerd on all nodes\n   c. Install etcd on control nodes\n   d. Install kubernetes control plane\n   e. Join worker nodes\n   f. Install Cilium CNI\n   g. Install Rook-Ceph storage\n\n4. Checkpoint after each step\n5. Monitor health checks\n6. Report completion\n```\n\n**Step 4**: Verify deployment\n\n```\nprovisioning cluster status my-cluster\n```\n\n### Configuration Hierarchy\n\nConfiguration values are resolved through a hierarchy:\n\n```\n1. System Defaults (provisioning/config/config.defaults.toml)\n   ↓ (overridden by)\n2. User Preferences (~/.config/provisioning/user_config.yaml)\n   ↓ (overridden by)\n3. Workspace Config (workspace/config/provisioning.yaml)\n   ↓ (overridden by)\n4. Infrastructure Config (workspace/infra/<name>/config.toml)\n   ↓ (overridden by)\n5. Environment Config (workspace/config/prod-defaults.toml)\n   ↓ (overridden by)\n6. Runtime Flags (--flag value)\n```\n\n**Example**:\n\n```\n# System default\n[servers]\ndefault_plan = "small"\n\n# User preference\n[servers]\ndefault_plan = "medium"  # Overrides system default\n\n# Infrastructure config\n[servers]\ndefault_plan = "large"   # Overrides user preference\n\n# Runtime\nprovisioning server create --plan xlarge  # Overrides everything\n```\n\n---\n\n## Use Cases\n\n### 1. **Multi-Cloud Kubernetes Deployment**\n\nDeploy Kubernetes clusters across different cloud providers with identical configuration.\n\n```\n# UpCloud cluster\nprovisioning cluster create k8s-prod --provider upcloud\n\n# AWS cluster (same config)\nprovisioning cluster create k8s-prod --provider aws\n```\n\n### 2. **Development → Staging → Production Pipeline**\n\nManage multiple environments with workspace switching.\n\n```\n# Development\nprovisioning workspace switch dev\nprovisioning cluster create app-stack\n\n# Staging (same config, different resources)\nprovisioning workspace switch staging\nprovisioning cluster create app-stack\n\n# Production (HA, larger resources)\nprovisioning workspace switch prod\nprovisioning cluster create app-stack\n```\n\n### 3. **Infrastructure as Code Testing**\n\nTest infrastructure changes before deploying to production.\n\n```\n# Test Kubernetes upgrade locally\nprovisioning test topology load kubernetes_3node | \\n  test env cluster kubernetes --version 1.29.0\n\n# Verify functionality\nprovisioning test env run <env-id>\n\n# Cleanup\nprovisioning test env cleanup <env-id>\n```\n\n### 4. **Batch Multi-Region Deployment**\n\nDeploy to multiple regions in parallel using Nickel batch workflows.\n\n```\n# schemas/batch/multi-region.ncl\n{\n  batch_workflow = {\n    operations = [\n      {\n        id = "eu-cluster"\n        type = "cluster"\n        region = "eu-west-1"\n        cluster = "app-stack"\n      }\n      {\n        id = "us-cluster"\n        type = "cluster"\n        region = "us-east-1"\n        cluster = "app-stack"\n      }\n      {\n        id = "asia-cluster"\n        type = "cluster"\n        region = "ap-south-1"\n        cluster = "app-stack"\n      }\n    ]\n    parallel_limit = 3  # All at once\n  }\n}\n```\n\n```\nprovisioning batch submit schemas/batch/multi-region.ncl\nprovisioning batch monitor <workflow-id>\n```\n\n### 5. **Automated Disaster Recovery**\n\nRecreate infrastructure from configuration.\n\n```\n# Infrastructure destroyed\nprovisioning workspace switch prod\n\n# Recreate from config\nprovisioning cluster create --infra backup-restore --wait\n\n# All services restored with same configuration\n```\n\n### 6. **CI/CD Integration**\n\nAutomated testing and deployment pipelines.\n\n```\n# .gitlab-ci.yml\ntest-infrastructure:\n  script:\n  - provisioning test quick kubernetes\n  - provisioning test quick postgres\n\ndeploy-staging:\n  script:\n  - provisioning workspace switch staging\n  - provisioning cluster create app-stack --check\n  - provisioning cluster create app-stack --yes\n\ndeploy-production:\n  when: manual\n  script:\n  - provisioning workspace switch prod\n  - provisioning cluster create app-stack --yes\n```\n\n---\n\n## Getting Started\n\n### Quick Start\n\n1. **Install Prerequisites**\n\n   ```bash\n   # Install Nushell (0.109.0+)\n   brew install nushell  # macOS\n\n   # Install Nickel (required for IaC)\n   brew install nickel  # macOS or from source\n\n   # Install SOPS (optional, for encrypted secrets)\n   brew install sops\n   ```\n\n2. **Add CLI to PATH**\n\n   ```bash\n   ln -sf "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning\n   ```\n\n3. **Initialize Workspace**\n\n   ```bash\n   provisioning workspace init my-project\n   cd my-project\n   ```\n\n3.5. **Generate Versions File** (Optional - for bash scripts)\n\n   ```bash\n   provisioning setup versions\n   # Creates /provisioning/core/versions with all tool and provider versions\n\n   # Use in your deployment scripts\n   source /provisioning/core/versions\n   echo "Deploying with Nushell $NU_VERSION and AWS CLI $PROVIDER_AWS_VERSION"\n   ```\n\n4. **Define Infrastructure (Nickel)**\n\n   ```bash\n   # Create workspace infrastructure schema\n   cat > workspace/infra/my-cluster.ncl <<'EOF'\n   {\n     metadata.name = "my-cluster"\n     metadata.provider = "upcloud"\n\n     infrastructure.servers = [\n       {name = "control-01", plan = "medium"}\n       {name = "worker-01", plan = "large"}\n     ]\n\n     services.taskservs = ["kubernetes", "cilium"]\n   }\n   EOF\n   ```\n\n5. **Deploy Infrastructure**\n\n   ```bash\n   # Validate configuration\n   provisioning config validate\n\n   # Check what will be created\n   provisioning server create --check\n\n   # Create servers\n   provisioning server create --yes\n\n   # Install Kubernetes\n   provisioning taskserv create kubernetes\n   ```\n\n### Learning Path\n\n1. **Start with Guides**\n\n   ```bash\n   provisioning sc                    # Quick reference\n   provisioning guide from-scratch    # Complete walkthrough\n   ```\n\n2. **Explore Examples**\n\n   ```bash\n   ls provisioning/examples/\n   ```\n\n3. **Read Architecture Docs**\n   - [Core Engine](provisioning/core/README.md)\n   - [CLI Architecture](.claude/features/cli-architecture.md)\n   - [Configuration System](.claude/features/configuration-system.md)\n   - [Batch Workflows](.claude/features/batch-workflow-system.md)\n\n4. **Try Test Environments**\n\n   ```bash\n   provisioning test quick kubernetes\n   provisioning test quick postgres\n   ```\n\n5. **Build Custom Extensions**\n   - Create custom task services\n   - Define cluster templates\n   - Write workflow automation\n\n---\n\n## Documentation Index\n\n### User & Operations Guides\n\nSee **[provisioning/docs/src/](provisioning/docs/src/)** for comprehensive documentation:\n\n- **Quick Start** - Get started in 10 minutes\n- **Command Reference** - Complete CLI command reference\n- **Nickel Configuration Guide** - IaC language and patterns\n- **Workspace Management** - Multi-workspace guide\n- **Test Environment Guide** - Testing infrastructure with containers\n- **Plugin Integration** - Native Rust plugins (10-50x faster)\n- **Security System** - Authentication, MFA, KMS, Cedar policies\n- **Operations** - Deployment, monitoring, incident response\n\n### Architecture & Design Decisions\n\nSee **[docs/src/architecture/](docs/src/architecture/)** for design patterns:\n\n- **System Architecture** - Multi-layer design\n- **ADRs (Architecture Decision Records)** - Major decisions including:\n  - ADR-011: Nickel Migration (from KCL)\n  - ADR-012: Nushell + Nickel plugin wrapper\n  - ADR-010: Configuration format strategy\n- **Multi-Repo Strategy** - Repository organization\n- **Integration Patterns** - How components interact\n\n### Development Guidelines\n\n- **[Repository Structure](docs/src/development/)** - Codebase organization\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute\n- **[Nushell Guidelines](.claude/guidelines/nushell/)** - Best practices\n- **[Nickel Guidelines](.claude/guidelines/nickel.md)** - IaC patterns\n- **[Rust Guidelines](.claude/guidelines/rust/)** - Rust conventions\n\n### API Reference\n\n- **REST API** - HTTP endpoints in `provisioning/docs/src/api-reference/`\n- **Nushell API** - Library functions and modules\n- **Provider API** - Cloud provider interface specification\n\n---\n\n## Project Status\n\n**Current Version**: v5.0.0-nickel (Production Ready) | **Date**: 2026-01-08\n\n### Completed Milestones\n\n- ✅ **v5.0.0** (2026-01-08) - **Nickel IaC Migration Complete**\n  - Full KCL→Nickel migration\n  - Schema-driven configuration system\n  - Type-safe lazy evaluation\n  - ~220 legacy files removed, ~250 new schema files added\n\n- ✅ **v3.6.0** (2026-01-08) - Version Management System\n  - Centralized tool and provider version management\n  - Bash-compatible versions file generation\n  - `provisioning setup versions` command\n  - Automatic provider version discovery from Nickel schemas\n  - Shell script integration with sourcing support\n\n- ✅ **v4.0.0** (2025-10-09) - Complete Security System (12 components, 39,699 lines)\n- ✅ **v3.5.0** (2025-10-07) - Platform Installer with TUI and CI/CD modes\n- ✅ **v3.4.0** (2025-10-06) - Test Environment Service with container management\n- ✅ **v3.3.0** (2025-09-30) - Interactive Guides system\n- ✅ **v3.2.0** (2025-09-30) - Modular CLI Architecture (84% code reduction)\n- ✅ **v3.1.0** (2025-09-25) - Batch Workflow System (85-90% token efficiency)\n- ✅ **v3.0.0** (2025-09-25) - Hybrid Orchestrator (Rust/Nushell)\n- ✅ **v2.0.5** (2025-10-02) - Workspace Switching system\n- ✅ **v2.0.0** (2025-09-23) - Configuration System (476+ accessors)\n- ✅ **v1.0.0** (2025-10-09) - Nushell Plugins Integration (10-50x performance)\n\n### Current Focus\n\n- **Nickel Ecosystem** - IDE support, LSP integration, schema libraries\n- **Platform Consolidation** - GitHub Actions CI/CD, cross-platform testing\n- **Extension Registry** - OCI-based distribution for task services and providers\n- **Documentation** - Complete Nickel migration guides, ADR updates\n\n---\n\n## Support and Community\n\n### Getting Help\n\n- **Documentation**: Start with `provisioning help` or `provisioning guide from-scratch`\n- **Issues**: Report bugs and request features on the issue tracker\n- **Discussions**: Join community discussions for questions and ideas\n\n### Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](docs/development/CONTRIBUTING.md) for guidelines.\n\n**Key areas for contribution**:\n\n- New task service definitions\n- Cloud provider implementations\n- Cluster templates\n- Documentation improvements\n- Bug fixes and testing\n\n---\n\n## License\n\nSee [LICENSE](LICENSE) file in project root.\n\n---\n\n**Maintained By**: Architecture Team\n**Last Updated**: 2026-01-08 (Version Management System v3.6.0 + Nickel v5.0.0 Migration Complete)\n**Current Branch**: nickel\n**Project Home**: [provisioning/](provisioning/)\n\n---\n\n## Recent Changes (2026-01-08)\n\n### Version Management System (v3.6.0)\n\n**What Changed**:\n- ✅ Implemented `provisioning setup versions` command\n- ✅ Generates bash-compatible `/provisioning/core/versions` file\n- ✅ Automatically discovers and includes all provider versions from Nickel schemas\n- ✅ Fixed to remove redundant metadata (all sources are Nickel)\n- ✅ Core tools with aliases: NUSHELL→NU, NICKEL, SOPS, AGE, K9S\n- ✅ Shell script integration: `source /provisioning/core/versions && echo $NU_VERSION`\n\n**Files Modified**:\n- `provisioning/core/nulib/lib_provisioning/setup/utils.nu` - Core implementation\n- `provisioning/core/nulib/main_provisioning/commands/setup.nu` - Command routing\n- `provisioning/core/nulib/lib_provisioning/workspace/enforcement.nu` - Workspace exemption\n- `provisioning/README.md` - Documentation updates\n\n**Generated File Example**:\n```\nNUSHELL_VERSION="0.109.1"\nNUSHELL_SOURCE="https://github.com/nushell/nushell/releases"\nNU_VERSION="0.109.1"\nNU_SOURCE="https://github.com/nushell/nushell/releases"\n\nNICKEL_VERSION="1.15.1"\nNICKEL_SOURCE="https://github.com/tweag/nickel/releases"\n\nPROVIDER_AWS_VERSION="2.32.11"\nPROVIDER_AWS_SOURCE="https://github.com/aws/aws-cli/releases"\n# ... and more providers\n```\n\n**Key Improvements**:\n- Clean metadata (no redundant `_LIB` fields - all sources are Nickel)\n- Automatic provider discovery from `extensions/providers/*/nickel/version.ncl`\n- Direct Nickel file parsing with JSON export\n- Zero dependency on environment variables or legacy systems\n- 100% bash/shell compatible for deployment scripts
