diff --git a/README.md b/README.md
index 102a5b0..9efbd3a 100644
--- a/README.md
+++ b/README.md
@@ -1,85 +1,149 @@
-# BitBuilder Hypervisor
-
-A git-ops-based, multi-tenant hypervisor platform built on systemd technologies for secure, isolated, and declaratively managed virtualization environments.
-
-## Overview
-
-BitBuilder Hypervisor is a next-generation hypervisor system that leverages the full power of systemd's virtualization and containerization capabilities to provide secure, isolated multi-tenant environments. Each tenant's configuration is version-controlled in Git repositories, enabling true infrastructure-as-code workflows with automatic provisioning and updates at boot time.
-
-## Key Features
-
--   **Git-Ops Native**: All configurations stored in Git repositories, pulled at boot time
--   **Multi-Tenant Isolation**: Complete separation between tenants using systemd's security features
--   **Immutable Host OS**: Read-only host system with all changes applied through git-controlled overlays
--   **Declarative Configuration**: Everything defined as code, no manual configuration required
--   **Zero-Trust Architecture**: Each tenant runs in completely isolated environments
--   **Dynamic Provisioning**: Automatic tenant setup and teardown based on git repository state
-
-## Core Technologies
-
-### Systemd Components
-
--   **systemd-boot**: UEFI boot manager for secure boot chain
--   **systemd-import-generator**: Automatic EFI image download and boot management
--   **systemd-vmspawn**: Lightweight VM spawning for tenant isolation
--   **systemd-nspawn**: Container spawning for application isolation
--   **systemd-networkd**: Network configuration and isolation
--   **systemd-homed**: User home directory management with encryption
--   **Portable Services**: Self-contained service images
--   **sysext/confext**: System and configuration extensions via overlayfs
--   **Varlink**: IPC protocol for service communication
-
-### Linux Userspace API Specifications
-
-BitBuilder Hypervisor implements and adheres to the [Linux Userspace API Specifications](https://uapi-group.org/specifications/):
-
--   [**Configuration Files Specification**](https://uapi-group.org/specifications/specs/configuration_files_specification/): Standardized locations for configuration management
--   [**Discoverable Partitions Specification (DPS)**](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/): Auto-discovery of partition semantics
--   [**Discoverable Disk Image (DDI)**](https://uapi-group.org/specifications/specs/discoverable_disk_image/): Self-describing system images
--   [**Extension Image**](https://uapi-group.org/specifications/specs/extension_image/): Layered extensions to base images
-    -   **sysext**: System Extension Images overlaid on `/usr/` and `/opt/`
-    -   **confext**: Configuration Extension Images overlaid on `/etc/`
--   [**Unified Kernel Image (UKI)**](https://uapi-group.org/specifications/specs/unified_kernel_image/): Combined kernel, initrd, and boot configuration
--   [**Boot Loader Specification (BLS)**](https://uapi-group.org/specifications/specs/boot_loader_specification/): Standardized boot configuration
-
-## Architecture Highlights
-
--   **Immutable Host**: The host OS boots from an immutable image downloaded via systemd-import-generator
--   **Tenant Isolation**: Each tenant runs in isolated systemd-vmspawn/nspawn instances
--   **Git-Based Configuration**: All tenant configurations pulled from dedicated Git repositories
--   **Dynamic Mount Generation**: Custom systemd generators create tenant-specific mount points
--   **Layered Extensions**: System capabilities extended through sysext/confext layers
-
-## Tenant Management
+# 🚀 BitBuilder Hypervisor
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![SystemD](https://img.shields.io/badge/SystemD-258+-blue?style=flat-square)](https://systemd.io/)
+[![Git-Ops](https://img.shields.io/badge/Git--Ops-Native-orange?style=flat-square)](https://www.gitops.tech/)
+[![UEFI](https://img.shields.io/badge/UEFI-Secure%20Boot-green?style=flat-square)](https://uefi.org/)
+
+> **🔥 A revolutionary git-ops-based, multi-tenant hypervisor platform built on systemd technologies for secure, isolated, and declaratively managed virtualization environments.**
+
+---
+
+## 🌟 Overview
+
+**BitBuilder Hypervisor** is a next-generation hypervisor system that leverages the full power of systemd's virtualization and containerization capabilities to provide secure, isolated multi-tenant environments. Each tenant's configuration is version-controlled in Git repositories, enabling true infrastructure-as-code workflows with automatic provisioning and updates at boot time.
+
+---
+
+## ✨ Key Features
+
+| Feature | Description | Benefits |
+|---------|-------------|----------|
+| 📚 **Git-Ops Native** | All configurations stored in Git repositories, pulled at boot time | Version control, atomic deployments, rollback capability |
+| 🏠 **Multi-Tenant Isolation** | Complete separation between tenants using systemd's security features | Zero trust architecture, cryptographic boundaries |
+| 🛡️ **Immutable Host OS** | Read-only host system with all changes applied through git-controlled overlays | Eliminates configuration drift, enhanced security |
+| 🎯 **Declarative Configuration** | Everything defined as code, no manual configuration required | Infrastructure as Code, automated provisioning |
+| 🔐 **Zero-Trust Architecture** | Each tenant runs in completely isolated environments | Hardware-backed security, namespace isolation |
+| ⚡ **Dynamic Provisioning** | Automatic tenant setup and teardown based on git repository state | Scalable operations, automated lifecycle management |
+
+---
+
+## 🔧 Core Technologies
+
+### 🖥️ Systemd Components
+
+| Component | Purpose | Features |
+|-----------|---------|----------|
+| 🚀 **systemd-boot** | UEFI boot manager for secure boot chain | Secure boot, UKI support, boot management |
+| ⬇️ **systemd-import-generator** | Automatic EFI image download and boot management | DDI support, automatic updates, verification |
+| 🖥️ **systemd-vmspawn** | Lightweight VM spawning for tenant isolation | Hardware virtualization, resource isolation |
+| 📦 **systemd-nspawn** | Container spawning for application isolation | Namespace isolation, security boundaries |
+| 🌐 **systemd-networkd** | Network configuration and isolation | Software-defined networking, tenant isolation |
+| 🏠 **systemd-homed** | User home directory management with encryption | Encrypted homes, hardware-backed auth |
+| 🎁 **Portable Services** | Self-contained service images | Application portability, dependency isolation |
+| 📋 **sysext/confext** | System and configuration extensions via overlayfs | Layered filesystems, immutable updates |
+| 🔗 **Varlink** | IPC protocol for service communication | Type-safe IPC, service discovery |
+
+### 📋 Linux Userspace API Specifications
+
+BitBuilder Hypervisor implements and adheres to the [**Linux Userspace API Specifications**](https://uapi-group.org/specifications/):
+
+| Specification | Purpose | Implementation |
+|---------------|---------|----------------|
+| 📄 [**Configuration Files Specification**](https://uapi-group.org/specifications/specs/configuration_files_specification/) | Standardized locations for configuration management | `/etc`, `/usr/lib`, `/run` hierarchy |
+| 💽 [**Discoverable Partitions Specification (DPS)**](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/) | Auto-discovery of partition semantics | GPT partition type GUIDs |
+| 📀 [**Discoverable Disk Image (DDI)**](https://uapi-group.org/specifications/specs/discoverable_disk_image/) | Self-describing system images | Unified disk images with metadata |
+| 🔧 [**Extension Image**](https://uapi-group.org/specifications/specs/extension_image/) | Layered extensions to base images | Overlay filesystem extensions |
+| ├── 🗂️ **sysext** | System Extension Images overlaid on `/usr/` and `/opt/` | Runtime system extensions |
+| └── 🛠️ **confext** | Configuration Extension Images overlaid on `/etc/` | Runtime configuration extensions |
+| 🚀 [**Unified Kernel Image (UKI)**](https://uapi-group.org/specifications/specs/unified_kernel_image/) | Combined kernel, initrd, and boot configuration | Single-file bootable images |
+| 🥾 [**Boot Loader Specification (BLS)**](https://uapi-group.org/specifications/specs/boot_loader_specification/) | Standardized boot configuration | systemd-boot integration |
+
+---
+
+## 🏗️ Architecture Highlights
+
+| Component | Description | Technology |
+|-----------|-------------|------------|
+| 🛡️ **Immutable Host** | The host OS boots from an immutable image downloaded via systemd-import-generator | DDI images, systemd-import |
+| 🏠 **Tenant Isolation** | Each tenant runs in isolated systemd-vmspawn/nspawn instances | Hardware virtualization, namespaces |
+| 📚 **Git-Based Configuration** | All tenant configurations pulled from dedicated Git repositories | Git-ops, declarative config |
+| 🗂️ **Dynamic Mount Generation** | Custom systemd generators create tenant-specific mount points | systemd generators, overlay mounts |
+| 🔧 **Layered Extensions** | System capabilities extended through sysext/confext layers | Extension images, overlayfs |
+
+---
+
+## 🏠 Tenant Management
+
+Each tenant in the BitBuilder Hypervisor follows a complete lifecycle management approach:
+
+```mermaid
+graph LR
+    A[📚 Git Repository] --> B[🔍 Discovery]
+    B --> C[⚡ Provisioning]
+    C --> D[🖥️ VM/Container]
+    D --> E[🔄 Updates]
+    E --> A
+    
+    style A fill:#e3f2fd
+    style B fill:#f3e5f5
+    style C fill:#e8f5e8
+    style D fill:#fff3e0
+    style E fill:#fce4ec
+```
 
-Each tenant in the BitBuilder Hypervisor:
+### 🔄 Tenant Lifecycle
+
+| Step | Process | Details |
+|------|---------|---------|
+| **1️⃣** | **Dedicated Git Repository** | Each tenant has its own configuration repository |
+| **2️⃣** | **Automatic Provisioning** | Boot-time provisioning via `setup-tenant@<tenantname>.service` |
+| **3️⃣** | **Isolated Execution** | Runs in systemd-vmspawn or systemd-nspawn instances |
+| **4️⃣** | **Custom Extensions** | Can have tenant-specific sysext/confext layers |
+| **5️⃣** | **Network Isolation** | Complete network isolation via systemd-networkd |
+| **6️⃣** | **Automatic Updates** | Updates automatically when Git repository changes |
+
+---
+
+## 🚀 Boot Process
+
+```mermaid
+sequenceDiagram
+    participant UEFI as 🔌 UEFI Boot
+    participant Boot as 🚀 systemd-boot
+    participant Import as ⬇️ systemd-import-gen
+    participant Host as 🖥️ Host OS
+    participant Git as 📚 Git Sync
+    participant Discovery as 🔍 Tenant Discovery
+    participant Provision as ⚡ Tenant Provisioning
+    
+    UEFI->>Boot: Load boot configuration
+    Boot->>Import: Download and verify EFI image
+    Import->>Host: Start immutable host OS
+    Host->>Git: Pull system configurations
+    Git->>Discovery: Scan for tenant configs
+    Discovery->>Provision: For each tenant:
+    Note over Provision: • Clone/pull tenant repo<br/>• Mount tenant directories<br/>• Apply sysext/confext layers<br/>• Start VM/container<br/>• Execute provisioning units
+```
 
-1.  Has a dedicated Git repository containing all configuration
-2.  Gets provisioned automatically at boot via `setup-tenant@<tenantname>.service`
-3.  Runs in isolated systemd-vmspawn or systemd-nspawn instances
-4.  Can have custom sysext/confext layers for additional functionality
-5.  Has complete network isolation via systemd-networkd
-6.  Gets automatic updates when Git repository changes
+### 🔄 Boot Sequence Details
 
-## Boot Process
+| Phase | Component | Action | Result |
+|-------|-----------|---------|---------|
+| **1️⃣** | 🔌 **UEFI Boot** | systemd-boot loads the boot configuration | Secure boot validation |
+| **2️⃣** | ⬇️ **Image Import** | systemd-import-generator downloads and verifies the host EFI image | DDI image verification |
+| **3️⃣** | 🖥️ **Host Boot** | Immutable host OS starts with minimal services | Base system ready |
+| **4️⃣** | 📚 **Git Sync** | System-level configurations pulled from Git repositories | Configuration sync |
+| **5️⃣** | 🔍 **Tenant Discovery** | Scan for tenant configurations in Git | Tenant enumeration |
+| **6️⃣** | ⚡ **Tenant Provisioning** | For each discovered tenant: provision resources | Multi-tenant setup |
 
-1.  **UEFI Boot**: systemd-boot loads the boot configuration
-2.  **Image Import**: systemd-import-generator downloads and verifies the host EFI image
-3.  **Host Boot**: Immutable host OS starts with minimal services
-4.  **Git Sync**: System-level configurations pulled from Git repositories
-5.  **Tenant Discovery**: Scan for tenant configurations in Git
-6.  **Tenant Provisioning**: For each tenant:
-    -   Clone/pull tenant Git repository
-    -   Mount tenant-specific directories
-    -   Apply sysext/confext layers
-    -   Start tenant VM/container via systemd-vmspawn/nspawn
-    -   Execute pre/post provisioning units
+---
 
-## Configuration Structure
+## 🏗️ Configuration Structure
 
-### Host Filesystem Hierarchy
+### 🗂️ Host Filesystem Hierarchy
 
-```
+```bash
 /
 ├── /boot/                              # Boot partition (read-only)
 │   └── efi/                            # EFI System Partition
@@ -144,34 +208,73 @@ Each tenant in the BitBuilder Hypervisor:
     └── tenants/                        # Runtime tenant data
 ```
 
-## Security Model
+---
+
+## 🛡️ Security Model
+
+### 🔒 Core Security Principles
+
+| Security Layer | Technology | Implementation | Benefit |
+|----------------|------------|----------------|---------|
+| 🏗️ **Immutable Infrastructure** | DDI, overlayfs | Host OS cannot be modified at runtime | Eliminates configuration drift |
+| 📚 **Git-Only Changes** | Git-ops workflow | All modifications through Git commits | Audit trail, rollback capability |
+| 🏠 **Tenant Isolation** | systemd security | Complete separation using multiple boundaries | Defense in depth |
+| 🔐 **Encrypted Storage** | systemd-homed, LUKS | Optional encryption for tenant data | Data protection at rest |
+| 🚀 **Secure Boot** | UEFI, TPM | Full secure boot chain support | Boot integrity verification |
+
+### 🔐 Multi-Layer Isolation
+
+```mermaid
+graph TB
+    subgraph "🏠 Tenant A"
+        VM1[🖥️ VM Instance]
+        NS1[📦 Container]
+    end
+    
+    subgraph "🏠 Tenant B" 
+        VM2[🖥️ VM Instance]
+        NS2[📦 Container]
+    end
+    
+    subgraph "🛡️ Security Boundaries"
+        PID[🔒 PID Namespaces]
+        NET[🌐 Network Isolation]
+        MOUNT[💾 Mount Namespaces]
+        USER[👤 User Namespaces]
+        CGROUP[⚙️ Resource Limits]
+        CAP[🔧 Capabilities]
+        MAC[🛡️ SELinux/AppArmor]
+    end
+    
+    VM1 --- PID
+    VM2 --- PID
+    NS1 --- NET
+    NS2 --- NET
+    VM1 --- MOUNT
+    VM2 --- USER
+    NS1 --- CGROUP
+    NS2 --- CAP
+    VM1 --- MAC
+```
 
--   **Immutable Infrastructure**: Host OS cannot be modified at runtime
--   **Git-Only Changes**: All modifications must go through Git commits
--   **Tenant Isolation**: Complete separation using systemd security features:
-    -   Separate namespaces (PID, network, mount, user)
-    -   Resource limits via cgroups
-    -   Capability restrictions
-    -   SELinux/AppArmor contexts
--   **Encrypted Storage**: Optional encryption for tenant data via systemd-homed
--   **Secure Boot**: Full UEFI secure boot chain support
+---
 
-## Git Repository Structure
+## 📁 Git Repository Structure
 
-### System Repository
+### 🏗️ System Repository
 
-```
+```bash
 bitbuilder-system/
 ├── .gitops/
 │   └── config.yaml                    # Git-ops configuration
 ├── generators/                        # Custom systemd generators
 │   ├── tenant-generator               # Tenant discovery and instantiation
-│   └── mount-generator               # Extension mount generation
-├── units/                            # System service units
-│   ├── tenant@.service               # Tenant instantiation template
-│   ├── tenant-infra@.service        # Infrastructure manager template
-│   └── tenant-network@.service      # Network setup template
-├── network/                          # Network configuration templates
+│   └── mount-generator                # Extension mount generation
+├── units/                             # System service units
+│   ├── tenant@.service                # Tenant instantiation template
+│   ├── tenant-infra@.service          # Infrastructure manager template
+│   └── tenant-network@.service        # Network setup template
+├── network/                           # Network configuration templates
 │   ├── 10-tenant-bridge.netdev
 │   ├── 10-tenant-bridge.network
 │   ├── 20-wg-tenant.netdev
@@ -182,99 +285,125 @@ bitbuilder-system/
 │   ├── base-tools.sysext.raw
 │   ├── monitoring.sysext.raw
 │   └── security.confext.raw
-└── tenants/                          # Tenant registry
-    └── registry.json                 # Active tenants list
+└── tenants/                           # Tenant registry
+    └── registry.json                  # Active tenants list
 ```
 
-### Tenant Configuration Repository
+### 🏠 Tenant Configuration Repository
 
-```
+```bash
 tenant-<name>/
 ├── metadata.json                     # Tenant metadata and requirements
 ├── infrastructure/                   # Infrastructure manager config
 │   ├── config.yaml                   # Infra manager configuration
-│   └── resource-limits.yaml         # Resource quotas
+│   └── resource-limits.yaml          # Resource quotas
 ├── network/                          # Network configuration
 │   ├── topology.yaml                 # Network topology definition
-│   ├── wireguard/                   # VPN configurations
-│   └── firewall/                    # Firewall rules
+│   ├── wireguard/                    # VPN configurations
+│   └── firewall/                     # Firewall rules
 ├── machines/                         # VM definitions
 │   └── <machine-name>/
-│       ├── config.yaml              # VM configuration
-│       └── cloud-init/              # Cloud-init data
+│       ├── config.yaml               # VM configuration
+│       └── cloud-init/               # Cloud-init data
 ├── containers/                       # Container definitions
 │   └── <container-name>/
-│       ├── config.yaml              # Container configuration
-│       └── rootfs-overlay/          # Filesystem overlays
+│       ├── config.yaml               # Container configuration
+│       └── rootfs-overlay/           # Filesystem overlays
 ├── extensions/                       # Tenant-specific extensions
-│   ├── sysext/                      # System extensions
+│   ├── sysext/                       # System extensions
 │   │   └── *.sysext.raw
-│   └── confext/                     # Configuration extensions
+│   └── confext/                      # Configuration extensions
 │       └── *.confext.raw
 ├── services/                         # Portable service definitions
 │   └── *.portable.raw
-├── users/                           # User definitions
+├── users/                            # User definitions
 │   └── <username>/
-│       └── homed-config.json       # systemd-homed configuration
+│       └── homed-config.json         # systemd-homed configuration
 └── scripts/
-    ├── pre-provision.sh             # Pre-provisioning script
-    ├── post-provision.sh            # Post-provisioning script
-    └── health-check.sh              # Health monitoring script
+    ├── pre-provision.sh              # Pre-provisioning script
+    ├── post-provision.sh             # Post-provisioning script
+    └── health-check.sh               # Health monitoring script
 ```
 
-### Template Repositories
+### 📋 Template Repositories
 
 BitBuilder provides standard templates for creating new tenants and resources:
 
-- **`tenant-infra-template`**: Infrastructure manager VM template
-- **`tenant-machine-template`**: VM instance template (systemd-vmspawn)
-- **`tenant-container-template`**: Container template (systemd-nspawn)
-- **`tenant-homed-template`**: User home directory template
-- **`sysext-template`**: System extension template
-- **`confext-template`**: Configuration extension template
+| Template | Purpose | Technology | Use Case |
+|----------|---------|------------|----------|
+| 🏗️ **`tenant-infra-template`** | Infrastructure manager VM template | systemd-vmspawn | Tenant orchestration |
+| 🖥️ **`tenant-machine-template`** | VM instance template | systemd-vmspawn | Application VMs |
+| 📦 **`tenant-container-template`** | Container template | systemd-nspawn | Containerized apps |
+| 🏠 **`tenant-homed-template`** | User home directory template | systemd-homed | User environments |
+| 🔧 **`sysext-template`** | System extension template | Extension images | System augmentation |
+| ⚙️ **`confext-template`** | Configuration extension template | Extension images | Config management |
+
+> 📖 See [**STACK.md**](STACK.md) for detailed template specifications and implementation details.
 
-See [STACK.md](STACK.md) for detailed template specifications.
+---
 
-## Advantages
+## 🎯 Advantages
 
--   **Version Control**: All infrastructure changes tracked in Git
--   **Rollback Capability**: Easy reversion to previous configurations
--   **Audit Trail**: Complete history of all changes
--   **Declarative Management**: Define desired state, not procedures
--   **Scalability**: Add/remove tenants by updating Git repositories
--   **Consistency**: Identical deployments from the same Git commits
--   **Testing**: Test configurations in staging before production
+| Advantage | Description | Impact |
+|-----------|-------------|---------|
+| 📚 **Version Control** | All infrastructure changes tracked in Git | Complete change history, diff capabilities |
+| 🔄 **Rollback Capability** | Easy reversion to previous configurations | Zero-downtime rollbacks, safety net |
+| 📋 **Audit Trail** | Complete history of all changes | Compliance, security, accountability |
+| 🎯 **Declarative Management** | Define desired state, not procedures | Reduced complexity, predictable outcomes |
+| 📈 **Scalability** | Add/remove tenants by updating Git repositories | Horizontal scaling, resource optimization |
+| ⚡ **Consistency** | Identical deployments from the same Git commits | Reproducible infrastructure, dev/prod parity |
+| 🧪 **Testing** | Test configurations in staging before production | Risk reduction, validation workflows |
 
-## Use Cases
+---
 
--   **Multi-Tenant Hosting**: Secure isolation for multiple customers
--   **Development Environments**: Reproducible developer workspaces
--   **Edge Computing**: Lightweight virtualization for edge deployments
--   **CI/CD Infrastructure**: Dynamic test environments
--   **Application Isolation**: Run untrusted workloads safely
--   **Compliance Environments**: Auditable, immutable infrastructure
+## 🎯 Use Cases
 
-## Requirements
+| Use Case | Industry | Benefits | Technology Stack |
+|----------|----------|----------|------------------|
+| 🏢 **Multi-Tenant Hosting** | Cloud Providers | Secure isolation for multiple customers | systemd-vmspawn, networking |
+| 👨‍💻 **Development Environments** | Software Development | Reproducible developer workspaces | systemd-nspawn, git-ops |
+| 🌐 **Edge Computing** | IoT, CDN | Lightweight virtualization for edge deployments | Minimal footprint, secure boot |
+| 🔄 **CI/CD Infrastructure** | DevOps | Dynamic test environments | Automated provisioning, git integration |
+| 🔒 **Application Isolation** | Security | Run untrusted workloads safely | Namespace isolation, capabilities |
+| 📋 **Compliance Environments** | Finance, Healthcare | Auditable, immutable infrastructure | Immutable OS, audit trails |
 
--   UEFI-capable hardware
--   systemd 258+ with all virtualization features enabled
--   Git client
--   Network connectivity for Git repository access
--   Sufficient resources for tenant VMs/containers
+---
 
-## Documentation
+## 📋 Requirements
 
--   [Technical Design](specs/DESIGN.md) - Detailed design documentation
--   [Architecture](specs/ARCHITECTURE.md) - System architecture overview
+### 🖥️ Hardware Requirements
 
-## License
+| Component | Minimum | Recommended | Purpose |
+|-----------|---------|-------------|---------|
+| 🔌 **UEFI Firmware** | UEFI 2.0+ | UEFI 2.8+ with Secure Boot | Boot integrity, hardware security |
+| ⚙️ **systemd Version** | 258+ | 260+ | All virtualization features enabled |
+| 📚 **Git Client** | 2.30+ | Latest stable | Repository operations, authentication |
+| 🌐 **Network Connectivity** | Basic | High-bandwidth | Git repository access, updates |
+| 💾 **Resources** | 8GB RAM, 100GB storage | 32GB RAM, 1TB NVMe SSD | Tenant VMs/containers |
+
+---
+
+## 📖 Documentation
+
+| Document | Description | Audience |
+|----------|-------------|----------|
+| 🎯 [**Technical Design**](specs/DESIGN.md) | Detailed design documentation | Architects, Developers |
+| 🏛️ [**Architecture**](specs/ARCHITECTURE.md) | System architecture overview | Technical Leaders, Ops |
+
+---
+
+## 📄 License
 
 \[License details to be added\]
 
-## Contributing
+---
+
+## 🤝 Contributing
 
 \[Contribution guidelines to be added\]
 
-## Support
+---
+
+## 🆘 Support
 
 \[Support information to be added\]
diff --git a/README2.md b/README2.md
index 5fb0dc5..64f0b47 100644
--- a/README2.md
+++ b/README2.md
@@ -1,37 +1,50 @@
-# BitBuilder Hypervisor
+# 🚀 BitBuilder Hypervisor
 
-**A Git-Ops Orchestrated Multi-Tenant Hypervisor Leveraging Advanced systemd Ecosystem Integration**
+[![Advanced Architecture](https://img.shields.io/badge/Architecture-Advanced-red?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor)
+[![SystemD Ecosystem](https://img.shields.io/badge/SystemD-Ecosystem-blue?style=flat-square)](https://systemd.io/)
+[![GitOps Native](https://img.shields.io/badge/GitOps-Native-orange?style=flat-square)](https://www.gitops.tech/)
+[![Multi-Tenant](https://img.shields.io/badge/Multi--Tenant-Secure-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor)
 
-BitBuilder Hypervisor implements a declarative, immutable infrastructure paradigm through git-ops methodology, providing secure multi-tenant virtualization environments via comprehensive systemd subsystem orchestration. The architecture implements tenant isolation through cryptographically-secured namespace boundaries, leveraging systemd's advanced service management, portable service architectures, and extension image composition patterns.
+> **🔥 A GitOps Orchestrated Multi-Tenant Hypervisor Leveraging Advanced systemd Ecosystem Integration**
 
-## Core Architecture Principles
+**BitBuilder Hypervisor** implements a declarative, immutable infrastructure paradigm through GitOps methodology, providing secure multi-tenant virtualization environments via comprehensive systemd subsystem orchestration. The architecture implements tenant isolation through cryptographically-secured namespace boundaries, leveraging systemd's advanced service management, portable service architectures, and extension image composition patterns.
 
-**Immutable Infrastructure**: The host operating system maintains complete immutability, with all configuration state externalized through git repository synchronization patterns and systemd generator composition.
+---
 
-**Declarative Tenant Management**: Each tenant's computational environment is defined through version-controlled configuration repositories, enabling atomic deployments, rollback capabilities, and audit trails through standard git operations.
+## 🎯 Core Architecture Principles
 
-**Cryptographic Isolation**: Multi-tenant security boundaries are enforced through systemd's namespace isolation primitives (systemd-nspawn, systemd-vmspawn), supplemented by cryptographic identity management via systemd-homed integration.
+### 🛡️ Foundation Pillars
 
-## Technical Implementation Stack
+| Principle | Implementation | Benefits |
+|-----------|----------------|----------|
+| 🏗️ **Immutable Infrastructure** | Host OS with complete immutability, configuration externalized through git repositories | Configuration drift elimination, enhanced security |
+| 🎯 **Declarative Tenant Management** | Version-controlled configuration repositories for each tenant | Atomic deployments, rollback capabilities, audit trails |
+| 🔐 **Cryptographic Isolation** | systemd namespace isolation with cryptographic identity management | Hardware-backed security boundaries, zero-trust architecture |
 
-### SystemD Subsystem Integration
+---
 
-- **systemd-generators**: Dynamic unit file generation for tenant-specific service orchestration
-- **systemd-import-generator**: Automated EFI image acquisition and boot environment preparation
-- **systemd-boot**: UEFI boot manager providing secure boot chain validation
-- **systemd-vmspawn**: Hardware-assisted virtualization for tenant isolation
-- **systemd-nspawn**: Container-based namespace isolation for lightweight tenants
-- **systemd-networkd**: Software-defined networking with tenant-scoped network namespaces
-- **systemd-homed**: Cryptographic user identity and home directory management
-- **Portable Services**: Tenant application deployment through self-contained service bundles
-- **Extension Images (sysext/confext)**: Immutable system and configuration layer composition
+## 🔧 Technical Implementation Stack
 
-### Inter-Process Communication
+### ⚙️ SystemD Subsystem Integration
 
-- **Varlink**: Type-safe, schema-validated IPC for service coordination and management interfaces
-- **D-Bus**: Legacy compatibility and systemd service lifecycle management
+| Component | Purpose | Advanced Features |
+|-----------|---------|-------------------|
+| 🔧 **systemd-generators** | Dynamic unit file generation for tenant-specific service orchestration | Template-based unit generation, dependency resolution |
+| ⬇️ **systemd-import-generator** | Automated EFI image acquisition and boot environment preparation | DDI verification, cryptographic validation |
+| 🚀 **systemd-boot** | UEFI boot manager providing secure boot chain validation | UKI support, secure boot integration |
+| 🖥️ **systemd-vmspawn** | Hardware-assisted virtualization for tenant isolation | QEMU integration, resource management |
+| 📦 **systemd-nspawn** | Container-based namespace isolation for lightweight tenants | Advanced namespace features, security contexts |
+| 🌐 **systemd-networkd** | Software-defined networking with tenant-scoped network namespaces | Advanced routing, network isolation |
+| 🏠 **systemd-homed** | Cryptographic user identity and home directory management | Hardware-backed authentication, encrypted storage |
+| 🎁 **Portable Services** | Tenant application deployment through self-contained service bundles | Application isolation, portable deployment |
+| 📋 **Extension Images** | Immutable system and configuration layer composition (sysext/confext) | Overlay filesystem management, atomic updates |
 
-### Git-Ops Orchestration Workflow
+### 🔗 Inter-Process Communication
+
+- 🔗 **Varlink**: Type-safe, schema-validated IPC for service coordination and management interfaces
+- 🔄 **D-Bus**: Legacy compatibility and systemd service lifecycle management
+
+### 🔄 GitOps Orchestration Workflow
 
 1. **Boot-time Repository Synchronization**: systemd-import-generator fetches immutable EFI images
 2. **Tenant Configuration Acquisition**: Git repository cloning/pulling for each tenant's declarative configuration
@@ -39,38 +52,38 @@ BitBuilder Hypervisor implements a declarative, immutable infrastructure paradig
 4. **Isolated Environment Provisioning**: systemd-vmspawn/systemd-nspawn instantiation with cryptographic boundaries
 5. **Extension Layer Composition**: sysext/confext mounting for tenant-specific software stacks
 
-## Features
+## ✨ Features
 
-### Advanced Multi-Tenancy
+### 🏠 Advanced Multi-Tenancy
 
 - **Cryptographic Tenant Isolation**: Each tenant operates within cryptographically-isolated namespaces
 - **Resource Quotas and Limits**: Comprehensive resource control through systemd slice units and cgroups v2
 - **Network Segmentation**: Software-defined networking with tenant-specific VLANs and firewall policies
 - **Storage Isolation**: Encrypted per-tenant storage volumes with key management integration
 
-### Git-Ops Configuration Management
+### 📚 GitOps Configuration Management
 
 - **Declarative Infrastructure as Code**: Complete tenant environments defined through version-controlled repositories
 - **Atomic Deployments**: Git commit-based deployment atomicity with automatic rollback capabilities
 - **Configuration Drift Detection**: Continuous monitoring of actual vs. desired state through git comparison
 - **Audit Trail**: Complete change history through git commit logs and cryptographic signatures
 
-### Portable Service Architecture
+### 🎁 Portable Service Architecture
 
 - **Self-Contained Application Bundles**: Applications packaged as portable systemd services with dependency isolation
 - **Extension Image Composition**: Layered filesystem approach for efficient storage and rapid provisioning
 - **Runtime Environment Abstraction**: Applications remain agnostic to underlying tenant infrastructure
 
-### Advanced Security Model
+### 🛡️ Advanced Security Model
 
 - **Hardware Security Module Integration**: TPM 2.0 support for attestation and key management
 - **Secure Boot Chain**: Complete boot process validation from UEFI through tenant initialization
 - **Cryptographic Identity Management**: systemd-homed integration for hardware-backed user authentication
 - **Network Security**: Mandatory access controls and network policy enforcement
 
-## System Requirements
+## 📋 System Requirements
 
-### Hardware Prerequisites
+### 🖥️ Hardware Prerequisites
 
 - **UEFI Firmware**: Modern UEFI implementation with Secure Boot support
 - **TPM 2.0**: Hardware security module for attestation and cryptographic operations
@@ -78,22 +91,22 @@ BitBuilder Hypervisor implements a declarative, immutable infrastructure paradig
 - **Memory**: Minimum 16GB RAM (32GB+ recommended for production workloads)
 - **Storage**: NVMe SSD storage recommended for optimal I/O performance
 
-### Software Dependencies
+### 💿 Software Dependencies
 
 - **Linux Kernel**: 6.1+ with systemd 254+ integration
 - **systemd**: Version 254+ with complete subsystem availability
 - **Git**: 2.40+ for repository operations and cryptographic signature validation
 - **Bun Runtime**: Latest stable release for TypeScript-based management tooling
 
-## Quick Start
+## 🚀 Quick Start
 
-### Host System Preparation
+### 🏗️ Host System Preparation
 
 ```bash
 # Configure systemd-boot with BitBuilder integration
 bootctl install --make-machine-id-directory=yes
 
-# Initialize git-ops repository structure
+# Initialize GitOps repository structure
 git clone https://github.com/your-org/bitbuilder-config.git /etc/bitbuilder
 cd /etc/bitbuilder && git submodule update --init --recursive
 
@@ -102,7 +115,7 @@ systemctl enable bitbuilder-bootstrap.service
 systemctl enable bitbuilder-tenant-monitor.timer
 ```
 
-### Tenant Configuration
+### 🏠 Tenant Configuration
 
 Create tenant repository structure:
 
@@ -124,7 +137,7 @@ tenant-example/
     └── keys/
 ```
 
-### Management Interface
+### 🎛️ Management Interface
 
 ```bash
 # Deploy new tenant configuration
@@ -137,9 +150,9 @@ bitbuilder monitor --tenant=example --metrics=cpu,memory,network,storage
 bitbuilder migrate --tenant=example --target-host=node-02.cluster.local
 ```
 
-## Configuration Architecture
+## 🏗️ Configuration Architecture
 
-### Repository Structure
+### 📁 Repository Structure
 
 BitBuilder implements a hierarchical configuration approach with three distinct repository types:
 
@@ -149,7 +162,7 @@ BitBuilder implements a hierarchical configuration approach with three distinct
 
 **Extension Repositories**: Shared extension images and portable services available across multiple tenants.
 
-### Service Generation Patterns
+### ⚙️ Service Generation Patterns
 
 SystemD generators dynamically create service definitions based on tenant configurations:
 
@@ -158,9 +171,9 @@ SystemD generators dynamically create service definitions based on tenant config
 - **tenant-storage@.service**: Encrypted storage volume mounting and key management
 - **tenant-monitor@.service**: Resource monitoring and policy enforcement
 
-## Security Model
+## 🔐 Security Model
 
-### Cryptographic Boundaries
+### 🔒 Cryptographic Boundaries
 
 Each tenant operates within a cryptographically-isolated environment:
 
@@ -169,22 +182,22 @@ Each tenant operates within a cryptographically-isolated environment:
 - **Network Segmentation**: Mandatory access control policies enforced at packet level
 - **Process Isolation**: Hardware-assisted virtualization with nested namespace boundaries
 
-### Audit and Compliance
+### 📋 Audit and Compliance
 
 - **Immutable Audit Log**: All configuration changes tracked through git commit signatures
 - **Real-time Monitoring**: Continuous security policy validation and violation detection
 - **Compliance Reporting**: Automated generation of security posture reports and attestations
 
-## Monitoring and Observability
+## 📊 Monitoring and Observability
 
-### Metrics Collection
+### 📈 Metrics Collection
 
 - **Resource Utilization**: Per-tenant CPU, memory, storage, and network metrics
 - **Security Events**: Authentication attempts, policy violations, and privilege escalations
 - **Performance Metrics**: Service startup times, git synchronization latency, and I/O throughput
 - **Health Checks**: Automated tenant environment validation and dependency verification
 
-### Management Interface
+### 🎛️ Management Interface
 
 BitBuilder provides a comprehensive management interface through:
 
@@ -193,7 +206,7 @@ BitBuilder provides a comprehensive management interface through:
 - **Web Dashboard**: Real-time monitoring and configuration management interface
 - **Git Hooks**: Automated validation and deployment triggers
 
-## Contributing
+## 🤝 Contributing
 
 BitBuilder follows strict Unix Philosophy principles and modern TypeScript development practices. All contributions must:
 
@@ -203,11 +216,11 @@ BitBuilder follows strict Unix Philosophy principles and modern TypeScript devel
 - Follow semantic versioning and conventional commit standards
 - Maintain backward compatibility with existing tenant configurations
 
-## License
+## 📄 License
 
 BitBuilder Hypervisor is released under the MIT License. See LICENSE file for complete terms and conditions.
 
-## Documentation
+## 📖 Documentation
 
 - [Technical Design](specs/DESIGN.md): Comprehensive system design and implementation details
 - [System Architecture](specs/ARCHITECTURE.md): Detailed architectural patterns and component interactions
diff --git a/STACK.md b/STACK.md
index 23d82c3..0652d10 100644
--- a/STACK.md
+++ b/STACK.md
@@ -1,42 +1,65 @@
 # 🏗️ BitBuilder Hypervisor Stack Architecture
 
-[![Technology](https://img.shields.io/badge/Technology-systemd-blue.svg)](https://systemd.io/)
-[![Architecture](https://img.shields.io/badge/Architecture-Multi--Tenant-green.svg)](https://github.com/bitbuilder-io/bitbuilder-hypervisor)
-[![GitOps](https://img.shields.io/badge/GitOps-Native-orange.svg)](https://gitops.tech/)
-[![Security](https://img.shields.io/badge/Security-Zero--Trust-red.svg)](https://en.wikipedia.org/wiki/Zero_trust_security_model)
+[![Stack Architecture](https://img.shields.io/badge/Stack-Architecture-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor)
+[![Templates](https://img.shields.io/badge/Templates-Multi--Tenant-blue?style=flat-square)](https://uapi-group.org/)
+[![Compliance](https://img.shields.io/badge/UAPI-Compliant-orange?style=flat-square)](https://uapi-group.org/specifications/)
+
+> **🧩 Comprehensive template system for creating fully compliant, multi-tenant rootfs filesystems with layered architecture and systemd integration.**
+
+---
 
 ## 📋 Table of Contents
 
-1. [🔧 Template System Overview](#template-system-overview)
-2. [🏢 Tenant Templates](#tenant-templates)
-3. [🧩 Extension Image Templates](#extension-image-templates)
-4. [🌐 Network Templates](#network-templates)
-5. [⚙️ Systemd Generators](#systemd-generators)
-6. [🚀 Tenant Instantiation Flow](#tenant-instantiation-flow)
-7. [📁 Directory Structure Compliance](#directory-structure-compliance)
+| Section | Description |
+|---------|-------------|
+| 🎯 [Template System Overview](#-template-system-overview) | Layered template architecture |
+| 🏠 [Tenant Templates](#-tenant-templates) | Infrastructure, VM, container templates |
+| 🔧 [Extension Image Templates](#-extension-image-templates) | sysext and confext templates |
+| 🌐 [Network Templates](#-network-templates) | Networking configuration patterns |
+| ⚙️ [Systemd Generators](#%EF%B8%8F-systemd-generators) | Dynamic unit generation |
+| 🔄 [Tenant Instantiation Flow](#-tenant-instantiation-flow) | Provisioning workflow |
+| ✅ [Directory Structure Compliance](#-directory-structure-compliance) | UAPI compliance validation |
 
-## 🔧 Template System Overview
+---
+
+## 🎯 Template System Overview
 
-> **💡 Key Concept:** BitBuilder Hypervisor uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the Linux Userspace API specifications.
+**BitBuilder Hypervisor** uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the [**Linux Userspace API specifications**](https://uapi-group.org/specifications/).
 
-### 📊 Template Categories
+### 🧩 Template Categories
 
-```text
-Templates
-├── 🏗️ Infrastructure Templates    # Management layer for each tenant
-├── 🖥️ Machine Templates           # VM templates (systemd-vmspawn)
-├── 📦 Container Templates         # Container templates (systemd-nspawn)
-├── 🏠 Homed Templates            # User home directory templates
-└── 🌐 Network Templates          # Network configuration templates
+```mermaid
+graph TB
+    T[📦 Templates] --> I[🏗️ Infrastructure Templates]
+    T --> M[🖥️ Machine Templates]
+    T --> C[📦 Container Templates]
+    T --> H[🏠 Homed Templates]
+    T --> N[🌐 Network Templates]
+
+    I --> IT[Management layer for each tenant]
+    M --> MT[VM templates - systemd-vmspawn]
+    C --> CT[Container templates - systemd-nspawn]
+    H --> HT[User home directory templates]
+    N --> NT[Network configuration templates]
+
+    style T fill:#e3f2fd
+    style I fill:#f3e5f5
+    style M fill:#e8f5e8
+    style C fill:#fff3e0
+    style H fill:#fce4ec
+    style N fill:#f1f8e9
 ```
 
-## 🏢 Tenant Templates
+---
+
+## 🏠 Tenant Templates
+
+### 1️⃣ Tenant Infrastructure Manager Template (`tenant-infra-template`)
 
-### 1. 🏗️ Tenant Infrastructure Manager Template (`tenant-infra-template`)
+> 🎯 **Purpose**: The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources.
 
-> **🔒 Security Note:** The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources.
+#### 🗂️ Repository Structure
 
-**📁 Repository Structure:**
 ```bash
 tenant-infra-template/
 ├── metadata.json                      # Template metadata
@@ -76,7 +99,7 @@ tenant-infra-template/
     └── health-check.sh               # Health monitoring
 ```
 
-**⚙️ metadata.json:**
+#### 📋 metadata.json Configuration
 ```json
 {
   "template": {
@@ -103,69 +126,69 @@ tenant-infra-template/
 }
 ```
 
-### 2. 🖥️ Tenant Machine Template (`tenant-machine-template`)
+### 2️⃣ Tenant Machine Template (`tenant-machine-template`)
 
-> **💻 Purpose:** Template for creating tenant VMs using systemd-vmspawn.
+Template for creating tenant VMs using systemd-vmspawn.
 
 **Repository Structure:**
 ```
 tenant-machine-template/
- metadata.json
- disk-image/                        # Base disk image
-    efi/                          # EFI partition
-       EFI/
-           systemd/
-               systemd-bootx64.efi
-    boot/                         # Boot partition
-       vmlinuz                   # Kernel
-       initrd.img               # Initial ramdisk
-    rootfs/                      # Root filesystem
-        etc/
-           os-release
-           machine-id           # Empty (generated)
-           systemd/
-               system/
-               network/
-        usr/                     # Minimal userspace
-        var/
- config/
-    vm-config.yaml
-    cloud-init/                  # Cloud-init templates
-        user-data
-        meta-data
- extensions/                      # VM-specific extensions
-     development.sysext.raw
-     monitoring.confext.raw
+├── metadata.json
+├── disk-image/                        # Base disk image
+│   ├── efi/                          # EFI partition
+│   │   └── EFI/
+│   │       └── systemd/
+│   │           └── systemd-bootx64.efi
+│   ├── boot/                         # Boot partition
+│   │   ├── vmlinuz                   # Kernel
+│   │   └── initrd.img               # Initial ramdisk
+│   └── rootfs/                      # Root filesystem
+│       ├── etc/
+│       │   ├── os-release
+│       │   ├── machine-id           # Empty (generated)
+│       │   └── systemd/
+│       │       ├── system/
+│       │       └── network/
+│       ├── usr/                     # Minimal userspace
+│       └── var/
+├── config/
+│   ├── vm-config.yaml
+│   └── cloud-init/                  # Cloud-init templates
+│       ├── user-data
+│       └── meta-data
+└── extensions/                      # VM-specific extensions
+    ├── development.sysext.raw
+    └── monitoring.confext.raw
 ```
 
-### 3. 📦 Tenant Container Template (`tenant-container-template`)
+### 3️⃣ Tenant Container Template (`tenant-container-template`)
 
-> **🐳 Purpose:** Template for creating tenant containers using systemd-nspawn.
+Template for creating tenant containers using systemd-nspawn.
 
 **Repository Structure:**
 ```
 tenant-container-template/
- metadata.json
- rootfs/                          # Container root filesystem
-    etc/
-       os-release
-       systemd/
-           system/
-              container-init.service
-           network/
-               80-container.network
-    usr/
-       bin/                    # Essential binaries
-       lib/
-    var/
-        lib/
- config/
-    nspawn-settings.conf        # systemd-nspawn settings
- scripts/
-     container-init.sh
+├── metadata.json
+├── rootfs/                          # Container root filesystem
+│   ├── etc/
+│   │   ├── os-release
+│   │   └── systemd/
+│   │       ├── system/
+│   │       │   └── container-init.service
+│   │       └── network/
+│   │           └── 80-container.network
+│   ├── usr/
+│   │   ├── bin/                     # Essential binaries
+│   │   └── lib/
+│   └── var/
+│       └── lib/
+├── config/
+│   └── nspawn-settings.conf         # systemd-nspawn settings
+└── scripts/
+    └── container-init.sh
 ```
 
-**nspawn-settings.conf:**
+#### ⚙️ nspawn-settings.conf
 ```ini
 [Exec]
 Boot=yes
@@ -182,39 +205,37 @@ PrivateUsersChown=yes
 BindReadOnly=/usr/lib/extensions
 ```
 
-### 4. 🏠 Tenant Homed Template (`tenant-homed-template`)
+### 4️⃣ Tenant Homed Template (`tenant-homed-template`)
 
-> **👥 Purpose:** Template for user home directories managed by systemd-homed.
+Template for user home directories managed by systemd-homed.
 
 **Repository Structure:**
 ```
 tenant-homed-template/
- metadata.json
- home-skeleton/                   # Default home structure
-    .config/
-       systemd/
-           user/               # User services
-    .local/
-       bin/                    # User binaries
-       share/
-    .ssh/                       # SSH configuration
-        authorized_keys.template
- config/
-    homed-config.json           # systemd-homed config
-    user-record.json           # User record template
- scripts/
-     home-provision.sh
+├── metadata.json
+├── home-skeleton/                   # Default home structure
+│   ├── .config/
+│   │   └── systemd/
+│   │       └── user/                # User services
+│   ├── .local/
+│   │   ├── bin/                     # User binaries
+│   │   └── share/
+│   └── .ssh/                        # SSH configuration
+│       └── authorized_keys.template
+├── config/
+│   ├── homed-config.json            # systemd-homed config
+│   └── user-record.json             # User record template
+└── scripts/
+    └── home-provision.sh
 ```
 
-## 🧩 Extension Image Templates
+## 🔧 Extension Image Templates
 
 ### 🔧 System Extension (sysext) Template
 
-> **💡 Note:** System extensions overlay the `/usr` and `/opt` directories to add tools and libraries.
-
-```bash
+```
 base-tools.sysext/
-├── usr/                            # Only /usr and /opt allowed
+├── usr/                             # Only /usr and /opt allowed
 │   ├── bin/
 │   │   ├── htop
 │   │   ├── tmux
@@ -227,7 +248,7 @@ base-tools.sysext/
         └── tools/
 ```
 
-**⚙️ extension-release.base-tools:**
+#### 📋 extension-release.base-tools
 ```ini
 ID=bitbuilder
 VERSION_ID=1.0
@@ -237,11 +258,9 @@ ARCHITECTURE=x86-64
 
 ### ⚙️ Configuration Extension (confext) Template
 
-> **🔧 Note:** Configuration extensions overlay the `/etc` directory to add configuration files.
-
-```bash
+```
 network-policies.confext/
-└── etc/                            # Only /etc allowed
+└── etc/                             # Only /etc allowed
     ├── systemd/
     │   └── network/
     │       ├── 20-wireguard.netdev
@@ -252,11 +271,9 @@ network-policies.confext/
 
 ## 🌐 Network Templates
 
-### 1. 🌉 Bridge Network Template
-
-> **🔗 Purpose:** Creates isolated bridge networks for tenant communication.
+### 1️⃣ Bridge Network Template
 
-**📄 /etc/systemd/network/10-tenant-bridge.netdev:**
+#### 📄 /usr/lib/systemd/network/10-tenant-bridge.netdev:
 ```ini
 [NetDev]
 Name=br-tenant-%i
@@ -270,7 +287,7 @@ HelloTimeSec=2
 MaxAgeSec=20
 ```
 
-**📄 /etc/systemd/network/10-tenant-bridge.network:**
+#### 📄 /usr/lib/systemd/system/10-tenant-bridge.network:
 ```ini
 [Match]
 Name=br-tenant-%i
@@ -290,11 +307,9 @@ DNS=10.%i.0.1
 EmitRouter=yes
 ```
 
-### 2. 🔐 WireGuard VPN Template
+### 2️⃣ WireGuard VPN Template
 
-> **🛡️ Security:** Provides encrypted VPN tunnels for secure tenant communication.
-
-**/etc/systemd/network/20-wg-tenant.netdev:**
+#### 📄 /usr/lib/systemd/system/20-wg-tenant.netdev:
 ```ini
 [NetDev]
 Name=wg-tenant-%i
@@ -311,7 +326,7 @@ Endpoint=${PEER_ENDPOINT}:51820
 PersistentKeepalive=25
 ```
 
-**/etc/systemd/network/20-wg-tenant.network:**
+#### 📄 /usr/lib/systemd/system/20-wg-tenant.network:
 ```ini
 [Match]
 Name=wg-tenant-%i
@@ -324,11 +339,9 @@ Destination=10.%i.100.0/24
 Scope=link
 ```
 
-### 3. 🌐 VXLAN Overlay Template
-
-> **🔗 Purpose:** Creates overlay networks for multi-host tenant communication.
+### 3️⃣ VXLAN Overlay Template
 
-**/etc/systemd/network/30-vxlan-tenant.netdev:**
+#### 📄 /usr/lib/systemd/system/30-vxlan-tenant.netdev:
 ```ini
 [NetDev]
 Name=vxlan-tenant-%i
@@ -341,7 +354,7 @@ DestinationPort=4789
 MacLearning=yes
 ```
 
-**/etc/systemd/network/30-vxlan-tenant.network:**
+#### 📄 /usr/lib/systemd/system/30-vxlan-tenant.network:
 ```ini
 [Match]
 Name=vxlan-tenant-%i
@@ -354,11 +367,9 @@ PVID=1
 EgressUntagged=1
 ```
 
-### 4. 🏷️ VLAN Segmentation Template
-
-> **📡 Purpose:** Provides VLAN-based network segmentation for tenant isolation.
+### 4️⃣ VLAN Segmentation Template
 
-**/etc/systemd/network/40-vlan-tenant.netdev:**
+#### 📄 /usr/lib/systemd/system/40-vlan-tenant.netdev:
 ```ini
 [NetDev]
 Name=vlan-tenant-%i
@@ -368,7 +379,7 @@ Kind=vlan
 Id=%i
 ```
 
-**/etc/systemd/network/40-vlan-tenant.network:**
+#### 📄 /usr/lib/systemd/system/40-vlan-tenant.network:
 ```ini
 [Match]
 Name=vlan-tenant-%i
@@ -382,9 +393,7 @@ RouteMetric=200
 UseDomains=route
 ```
 
-### 5. 🗂️ Network Namespace Template
-
-> **🔒 Isolation:** Creates isolated network namespaces for complete tenant network separation.
+### 5️⃣ Network Namespace Template
 
 **/usr/lib/systemd/system/netns-tenant@.service:**
 ```ini
@@ -405,9 +414,7 @@ WantedBy=multi-user.target
 
 ## ⚙️ Systemd Generators
 
-> **🤖 Automation:** Systemd generators automatically create service units for tenant management based on Git repository configurations.
-
-### 1. 🔍 Tenant Discovery Generator
+### 1️⃣ Tenant Discovery Generator
 
 **/usr/lib/systemd/system-generators/tenant-generator:**
 ```bash
@@ -420,7 +427,7 @@ TENANT_REGISTRY="/var/lib/bitbuilder/tenants.json"
 generate_tenant_units() {
     local tenant_id="$1"
     local tenant_config="$2"
-    
+
     # Generate main tenant service
     cat > "${GENERATOR_DIR}/tenant@${tenant_id}.service" <<EOF
 [Unit]
@@ -483,15 +490,13 @@ if [[ -f "$TENANT_REGISTRY" ]]; then
     jq -r '.tenants[] | @base64' "$TENANT_REGISTRY" | while read -r tenant_data; do
         tenant_json=$(echo "$tenant_data" | base64 -d)
         tenant_id=$(echo "$tenant_json" | jq -r '.id')
-        
+
         generate_tenant_units "$tenant_id" "$tenant_json"
     done
 fi
 ```
 
-### 2. 📂 Mount Generator
-
-> **💾 Storage:** Automatically generates mount units for tenant directories and extension overlays.
+### 2️⃣ Mount Generator
 
 **/usr/lib/systemd/system-generators/mount-generator:**
 ```bash
@@ -503,7 +508,7 @@ TENANT_BASE="/var/lib/tenants"
 
 generate_extension_mounts() {
     local tenant_id="$1"
-    
+
     # Generate sysext mount
     cat > "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-sysext.mount" <<EOF
 [Unit]
@@ -548,37 +553,31 @@ if [[ -d "$TENANT_BASE" ]]; then
 fi
 ```
 
-## 🚀 Tenant Instantiation Flow
+## 🔄 Tenant Instantiation Flow
 
-### 1. ✅ Enable Tenant
-
-> **⚡ Quick Start:** Simple command to enable and start a new tenant.
+### 1️⃣ Enable Tenant
 
 ```bash
 # Enable and start a new tenant
 systemctl enable --now tenant@tenant123.service
 ```
 
-### 2. 🔄 Instantiation Process
-
-> **📊 Workflow:** Visual representation of the tenant startup process.
+### 2️⃣ Instantiation Process
 
 ```mermaid
 graph TD
-    A[🎯 systemctl enable tenant@ID] --> B[🔍 Tenant Generator]
-    B --> C[📖 Read tenant registry]
-    C --> D[📥 Clone Git repositories]
-    D --> E[⚙️ Generate systemd units]
-    E --> F[🌐 Setup network namespace]
-    F --> G[📂 Mount extensions]
-    G --> H[🖥️ Start infra manager VM]
-    H --> I[🔧 Provision tenant resources]
-    I --> J[🚀 Start tenant workloads]
+    A[systemctl enable tenant@ID] --> B[Tenant Generator]
+    B --> C[Read tenant registry]
+    C --> D[Clone Git repositories]
+    D --> E[Generate systemd units]
+    E --> F[Setup network namespace]
+    F --> G[Mount extensions]
+    G --> H[Start infra manager VM]
+    H --> I[Provision tenant resources]
+    I --> J[Start tenant workloads]
 ```
 
-### 3. 🏗️ Generated Unit Hierarchy
-
-> **📋 Dependencies:** Overview of systemd service dependencies.
+### 3️⃣ Generated Unit Hierarchy
 
 ```
 tenant@tenant123.service
@@ -592,30 +591,30 @@ tenant@tenant123.service
      br-tenant-123.netdev
 ```
 
-## 📁 Directory Structure Compliance
+## ✅ Directory Structure Compliance
 
-### 📋 Linux File System Hierarchy Compliance
+### 📁 Linux File System Hierarchy Compliance
 
-> **✅ Standards:** Each template ensures compliance with the Linux File System Hierarchy specification for maximum compatibility.
+Each template ensures compliance with the Linux File System Hierarchy specification:
 
-#### 1. 🏠 **Root Filesystem Requirements:**
-   - ✅ `/etc/os-release` or `/usr/lib/os-release` present
-   - ✅ Proper symlink from `/usr/lib/os-release` to `/etc/os-release`
-   - ✅ No files in `/` root directory itself
+1. **Root Filesystem Requirements:
+   - `/etc/os-release` or `/usr/lib/os-release` present
+   - Proper symlink from `/usr/lib/os-release` to `/etc/os-release`
+   - No files in `/` root directory itself
 
-#### 2. 🧩 **Extension Image Requirements:**
-   - **sysext:** Only `/usr/` and `/opt/` directories
-   - **confext:** Only `/etc/` directory
-   - ✅ Proper `extension-release` files in correct locations
+2. **Extension Image Requirements:
+   - sysext: Only `/usr/` and `/opt/` directories
+   - confext: Only `/etc/` directory
+   - Proper `extension-release` files in correct locations
 
-#### 3. 🔐 **Verification Structure:**
-   - 📍 VOA hierarchy at `/etc/voa/` and `/usr/share/voa/`
-   - 🔑 Proper certificate fingerprint naming
-   - 📜 ASCII-armored OpenPGP files
+3. **Verification Structure:
+   - VOA hierarchy at `/etc/voa/` and `/usr/share/voa/`
+   - Proper certificate fingerprint naming
+   - ASCII-armored OpenPGP files
 
-### 🔍 Template Validation
+### ✅ Template Validation
 
-> **✅ Quality Assurance:** Each template includes a validation script to ensure compliance and functionality.
+Each template includes a validation script:
 
 ```bash
 #!/bin/bash
@@ -623,40 +622,32 @@ tenant@tenant123.service
 
 validate_rootfs() {
     local rootfs="$1"
-    
+
     # Check for required files
     [[ -f "$rootfs/etc/os-release" ]] || error "Missing /etc/os-release"
     [[ -L "$rootfs/usr/lib/os-release" ]] || error "Missing /usr/lib/os-release symlink"
-    
+
     # Validate directory structure
     for dir in etc usr var proc sys dev run tmp; do
         [[ -d "$rootfs/$dir" ]] || error "Missing /$dir directory"
     done
-    
+
     # Check permissions
     [[ $(stat -c %a "$rootfs/tmp") == "1777" ]] || error "Invalid /tmp permissions"
-    
+
     echo "Template validation successful"
 }
 ```
 
 ## 🎯 Conclusion
 
-> **🏆 Summary:** The BitBuilder Hypervisor template system delivers enterprise-grade multi-tenancy with modern GitOps workflows.
+This template system provides:
 
-### ✨ Key Benefits
-
-1. **📏 Standardization**: All tenants use consistent, validated templates
-2. **✅ Compliance**: Full adherence to Linux Userspace API specifications  
-3. **🔄 Flexibility**: Multiple template types for different use cases
-4. **🔒 Security**: Layered isolation with proper namespace separation
-5. **🤖 Automation**: Systemd generators handle all instantiation logic
-6. **🌐 Networking**: Comprehensive network isolation and connectivity options
-
-### 🚀 Platform Advantages
-
-The combination of **Git-based configuration**, **systemd integration**, and **compliant filesystem templates** creates a robust, secure, and manageable multi-tenant hypervisor platform that scales from development to enterprise production environments.
-
----
+1. **Standardization**: All tenants use consistent, validated templates
+2. **Compliance**: Full adherence to Linux Userspace API specifications
+3. **Flexibility**: Multiple template types for different use cases
+4. **Security**: Layered isolation with proper namespace separation
+5. **Automation**: Systemd generators handle all instantiation logic
+6. **Networking**: Comprehensive network isolation and connectivity options
 
-> **💡 Next Steps:** Ready to deploy? Check out our [deployment guide](specs/DESIGN.md) and [architecture overview](specs/ARCHITECTURE.md) for implementation details.
\ No newline at end of file
+The combination of Git-based configuration, systemd integration, and compliant filesystem templates creates a robust, secure, and manageable multi-tenant hypervisor platform.
diff --git a/specs/ARCHITECTURE.md b/specs/ARCHITECTURE.md
index 5c739fc..fb6a70b 100644
Binary files a/specs/ARCHITECTURE.md and b/specs/ARCHITECTURE.md differ
diff --git a/specs/DESIGN.md b/specs/DESIGN.md
index d93d5c7..f3d184e 100644
Binary files a/specs/DESIGN.md and b/specs/DESIGN.md differ