refactor: Restructure project for Docker compliance and documentation

- Move documentation to docs/ directory for better organization
- Add bin/ directory for utility scripts
- Add lib/ for shared library functions
- Update all build scripts to ensure strict Docker compliance
- Enhance AGENTS.md with Docker container requirements
- Create comprehensive compliance and security documentation
- Reorganize test suite with improved structure
- Remove obsolete Dockerfile and archive documentation
- Add final security compliance report

BREAKING CHANGE: Restructured project layout with moved documentation directories

💘 Generated with Crush

Assisted-by: GLM-4.6 via Crush <crush@charm.land>

src/build-iso.sh

@@ -1,82 +1,218 @@
 #!/bin/bash
-# Main ISO build script
+# Main ISO build script - STRICTLY Docker-based
 set -euo pipefail
 
-# Configuration variables
-readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-readonly PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
-readonly OUTPUT_DIR="${PROJECT_ROOT}/output"
-readonly CONFIG_DIR="${PROJECT_ROOT}/config"
+echo "=== KNEL-Football ISO Build ==="
+echo "All operations performed in Docker container"
 
-# Function to validate environment
+# Configuration
+readonly PROJECT_NAME="knel-football-secure"
+readonly VERSION="1.0.0"
+readonly DOCKER_IMAGE="knel-football-dev:latest"
+readonly BUILD_TIMEOUT="3600" # 1 hour timeout
+
+# Function to validate Docker environment
 validate_environment() {
-    echo "Validating build environment..."
-    
-    # Check for required tools
-    local required_tools=("lb" "debootstrap" "mksquashfs")
-    for tool in "${required_tools[@]}"; do
-        if ! command -v "$tool" > /dev/null 2>&1; then
-            echo "Error: Required tool '$tool' not found"
-            exit 1
-        fi
-    done
-    
-    # Verify configuration directory
-    if [[ ! -d "$CONFIG_DIR" ]]; then
-        echo "Error: Configuration directory not found at $CONFIG_DIR"
-        exit 1
-    fi
-    
-    echo "Environment validation successful."
+  echo "Validating Docker environment..."
+
+  # Check for Docker
+  if ! command -v docker >/dev/null 2>&1; then
+    echo "Error: Docker not found"
+    exit 1
+  fi
+
+  # Check if Docker image exists
+  if ! docker image inspect "$DOCKER_IMAGE" >/dev/null 2>&1; then
+    echo "Error: Docker image '$DOCKER_IMAGE' not found"
+    echo "Run: docker build -t $DOCKER_IMAGE ."
+    exit 1
+  fi
+
+  echo "Docker environment validation successful."
 }
 
-# Function to prepare build environment
-prepare_build() {
-    echo "Preparing build environment..."
-    
-    # Create output directory
-    mkdir -p "$OUTPUT_DIR"
-    
-    # Initialize live-build configuration
-    lb clean --purge
-    lb config
-    
-    echo "Build environment prepared."
-}
-
-# Function to build ISO
+# Function to build ISO in Docker container
 build_iso() {
-    echo "Building secure Debian ISO..."
+  echo "Building secure Debian ISO in Docker container..."
+
+  # Clean up any existing container
+  docker rm -f "$PROJECT_NAME-build" 2>/dev/null || true
+
+  # Run build in Docker container with proper volumes
+  docker run --name "$PROJECT_NAME-build" \
+    --rm \
+    -v "$(pwd)":/workspace:ro \
+    -v "$(pwd)/tmp":/build \
+    -v "$(pwd)/output":/output \
+    -e TZ="UTC" \
+    -e DEBIAN_FRONTEND="noninteractive" \
+    -e LC_ALL="C" \
+    "$DOCKER_IMAGE" \
+    bash -c "
+echo '=== Building KNEL-Football Secure OS ==='
+echo 'All operations performed inside container'
+echo 'Workspace: /workspace (read-only)'
+echo 'Build: /build'
+echo 'Output: /output'
+
+# Install build tools if not present
+if ! command -v lb > /dev/null 2>&1; then
+    echo 'Installing build tools...'
+    apt-get update -qq
+    apt-get install -y live-build xorriso grub-pc-bin syslinux-utils
+fi
+
+# Create build environment
+cd /build
+rm -rf ./*
+echo 'Configuring live-build...'
+lb config \
+    --distribution testing \
+    --architectures amd64 \
+    --archive-areas 'main contrib non-free' \
+    --mode debian \
+    --chroot-filesystem squashfs \
+    --binary-filesystem iso9660 \
+    --binary-images iso-hybrid \
+    --iso-application 'KNEL-Football Secure OS' \
+    --iso-publisher 'KNEL-Football Security Team' \
+    --iso-volume 'KNEL-Football Secure' \
+    --linux-packages 'linux-image-amd64 linux-headers-amd64' \
+    --debian-installer true \
+    --debian-installer-gui true \
+    --win32-loader true \
+    --memtest memtest86+ \
+    --source false \
+    --apt-indices false \
+    --apt-source-archives false
+
+# Apply configuration from workspace
+if [ -d /workspace/config ]; then
+    echo 'Applying custom configuration...'
+    cp -r /workspace/config/* ./
+fi
+
+# Build ISO
+echo 'Starting ISO build (30-60 minutes)...'
+timeout $BUILD_TIMEOUT lb build
+
+if [ \$? -eq 0 ]; then
+    echo '✓ Build completed successfully!'
     
-    # Execute live-build
-    lb build
-    
-    # Move output files to output directory
-    if [[ -f "binary.hybrid.iso" ]]; then
-        mv "binary.hybrid.iso" "${OUTPUT_DIR}/knel-football.iso"
+    # Find and process ISO
+    ISO_FILE=\$(find . -name '*.iso' -type f | head -1)
+    if [ -n \"\$ISO_FILE\" ]; then
+        echo \"✓ ISO created: \$ISO_FILE\"
+        
+        # Generate checksums
+        sha256sum \"\$ISO_FILE\" > \"\${ISO_FILE}.sha256\"
+        md5sum \"\$ISO_FILE\" > \"\${ISO_FILE}.md5\"
+        
+        # Create KNEL-Football branded name
+        FINAL_ISO=\"${PROJECT_NAME}-v${VERSION}.iso\"
+        mv \"\$ISO_FILE\" \"\$FINAL_ISO\"
+        mv \"\${ISO_FILE}.sha256\" \"\${FINAL_ISO}.sha256\"
+        mv \"\${ISO_FILE}.md5\" \"\${FINAL_ISO}.md5\"
+        
+        # Copy artifacts to output volume
+        cp \"\$FINAL_ISO\" \"\${FINAL_ISO}.sha256\" \"\${FINAL_ISO}.md5\" /output/
+        
+        # Create build report
+        cat > /output/BUILD-REPORT.txt << REPORT
+KNEL-Football Secure OS Build Report
+=================================
+Build Date: \$(date)
+Build Environment: Docker Container ($DOCKER_IMAGE)
+Version: $VERSION
+Architecture: x86_64
+
+Files Created:
+- $PROJECT_NAME-v$VERSION.iso (bootable ISO)
+- $PROJECT_NAME-v$VERSION.sha256 (SHA256 checksum)
+- $PROJECT_NAME-v$VERSION.md5 (MD5 checksum)
+
+Technical Specifications:
+- Base Distribution: Debian Testing
+- Boot Support: Hybrid UEFI/Legacy BIOS
+- Filesystem: SquashFS + ISO9660
+- Package Manager: apt
+- Init System: systemd
+
+Features:
+- Debian Installer with GUI
+- Full firmware support
+- Security configurations
+- Memtest86+ memory testing
+
+Build Status: SUCCESSFUL
+
+Next Steps:
+1. Test ISO on target hardware
+2. Validate installation process
+3. Apply KNEL-Football security configurations
+4. Deploy to production environment
+
+ISO Information:
+Type: Hybrid (UEFI + Legacy BIOS compatible)
+Checksum: SHA256 (see .sha256 file)
+
+Contact: KNEL-Football IT Security Team
+Generated: \$(date)
+REPORT
+        
+        echo '✓ Build report created'
+        echo '✓ All artifacts copied to /output/'
+        
+        # Display ISO info
+        if [ -f \"/output/\$FINAL_ISO\" ]; then
+            echo ''
+            echo 'ISO Details:'
+            echo \"File: \$FINAL_ISO\"
+            echo \"Size: \$(du -h \"/output/\$FINAL_ISO\" | cut -f1)\"
+            echo \"SHA256: \$(cat \"/output/\${FINAL_ISO}.sha256\" | cut -d' ' -f1)\"
+        fi
+        
     else
-        echo "Error: ISO file not generated"
+        echo '✗ No ISO file found'
         exit 1
     fi
-    
-    # Generate checksum
-    cd "$OUTPUT_DIR"
-    sha256sum "knel-football.iso" > "knel-football.iso.sha256"
-    cd - > /dev/null
-    
-    echo "ISO build completed successfully."
-    echo "Output: ${OUTPUT_DIR}/knel-football.iso"
+else
+    echo '✗ Build failed or timed out'
+    exit 1
+fi
+"
+
+  # Check if build succeeded
+  echo ""
+  echo "=== BUILD COMPLETION CHECK ==="
+
+  if [ -f "output/$PROJECT_NAME-v$VERSION.iso" ]; then
+    echo "✓ BUILD SUCCESSFUL!"
+    echo "✓ ISO created: $PROJECT_NAME-v$VERSION.iso"
+    echo "✓ Size: $(du -h "output/$PROJECT_NAME-v$VERSION.iso" | cut -f1)"
+    echo "✓ SHA256: $(cat "output/$PROJECT_NAME-v$VERSION.sha256" | cut -d' ' -f1)"
+    echo "All operations performed in Docker container - NO host modifications"
+    return 0
+  else
+    echo "✗ BUILD FAILED"
+    echo "Check Docker container output for errors"
+    return 1
+  fi
 }
 
 # Main execution
 main() {
-    echo "Starting KNEL-Football secure ISO build..."
-    
-    validate_environment
-    prepare_build
-    build_iso
-    
-    echo "Build process completed successfully!"
+  echo "Starting KNEL-Football secure ISO build..."
+
+  # Ensure output directory exists
+  mkdir -p output
+  mkdir -p tmp
+
+  validate_environment
+  build_iso
+
+  echo "Build process completed successfully!"
+  echo "All operations performed in Docker container - NO host system modifications"
 }
 
-main "$@"
+main "$@"

src/build.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# KNEL-Football Secure OS Docker Build Script
+# STRICTLY Docker-only workflow - NO host system modifications
+
+set -euo pipefail
+
+echo "=== KNEL-Football Secure OS Build ==="
+echo "Environment: Docker Container Only"
+echo "Workspace: Docker Volume"
+
+# Configuration
+PROJECT_NAME="knel-football-secure"
+VERSION="1.0.0"
+DOCKER_IMAGE="knel-football-dev:latest" # Using required knel-football-dev image
+BUILD_TIMEOUT="3600"                    # 1 hour timeout
+
+# Cleanup function
+cleanup() {
+  echo "Cleaning up Docker resources..."
+  docker rm -f "$PROJECT_NAME-build" 2>/dev/null || true
+  echo "✓ Docker cleanup completed"
+}
+
+trap cleanup EXIT
+
+# Ensure output directory exists (on host)
+mkdir -p output tmp
+echo "✓ Output directory: $(pwd)/output"
+echo "✓ Build directory: $(pwd)/tmp"
+
+echo ""
+echo "=== Starting Docker Build ==="
+
+# Run entire build process in Docker container
+docker run --name "$PROJECT_NAME-build" \
+  --rm \
+  -v "$(pwd)":/workspace:ro \
+  -v "$(pwd)/tmp":/build \
+  -v "$(pwd)/output":/output \
+  -e TZ="UTC" \
+  -e DEBIAN_FRONTEND="noninteractive" \
+  -e LC_ALL="C" \
+  "$DOCKER_IMAGE" \
+  bash -c "
+echo '=== Building KNEL-Football Secure OS in Docker ==='
+echo 'All operations performed inside container'
+echo 'Workspace: /workspace (read-only)'
+echo 'Build: /build'
+echo 'Output: /output'
+echo 'Build Version: $VERSION'
+echo ''
+
+# Install build tools
+echo 'Installing build tools...'
+apt-get update -qq
+apt-get install -y live-build xorriso grub-pc-bin syslinux-utils
+
+# Create build environment
+cd /build
+rm -rf ./*
+
+# Configure live-build
+echo 'Configuring live-build...'
+lb config \
+    --distribution testing \
+    --architectures amd64 \
+    --archive-areas 'main contrib non-free' \
+    --mode debian \
+    --chroot-filesystem squashfs \
+    --binary-filesystem iso9660 \
+    --binary-images iso-hybrid \
+    --iso-application 'KNEL-Football Secure OS' \
+    --iso-publisher 'KNEL-Football Security Team' \
+    --iso-volume 'KNEL-Football Secure' \
+    --linux-packages 'linux-image-amd64 linux-headers-amd64' \
+    --debian-installer true \
+    --debian-installer-gui true \
+    --win32-loader true \
+    --memtest memtest86+ \
+    --source false \
+    --apt-indices false \
+    --apt-source-archives false
+
+# Apply configuration from workspace if available
+if [ -d /workspace/config ]; then
+    echo 'Applying custom configuration...'
+    cp -r /workspace/config/* ./
+fi
+
+# Build ISO
+echo 'Starting ISO build (30-60 minutes)...'
+timeout $BUILD_TIMEOUT lb build
+
+if [ $? -eq 0 ]; then
+    echo '✓ Build completed successfully!'
+    
+    # Find and process ISO
+    ISO_FILE=$(find . -name '*.iso' -type f | head -1)
+    if [ -n \"$ISO_FILE\" ]; then
+        echo \"✓ ISO created: $ISO_FILE\"
+        
+        # Generate checksums
+        sha256sum \"$ISO_FILE\" > \"${ISO_FILE}.sha256\"
+        md5sum \"$ISO_FILE\" > \"${ISO_FILE}.md5\"
+        
+        # Create KNEL-Football branded name
+        FINAL_ISO=\"${PROJECT_NAME}-v${VERSION}.iso\"
+        mv \"$ISO_FILE\" \"$FINAL_ISO\"
+        mv \"${ISO_FILE}.sha256\" \"${FINAL_ISO}.sha256\"
+        mv \"${ISO_FILE}.md5\" \"${FINAL_ISO}.md5\"
+        
+        # Copy artifacts to output volume (host accessible)
+        cp \"$FINAL_ISO\" \"${FINAL_ISO}.sha256\" \"${FINAL_ISO}.md5\" /output/
+        
+        # Create build report
+        cat > /output/BUILD-REPORT.txt << REPORT
+KNEL-Football Secure OS Build Report
+=================================
+Build Date: $(date)
+Build Environment: Docker Container ($DOCKER_IMAGE)
+Version: $VERSION
+Architecture: x86_64
+
+Files Created:
+- $PROJECT_NAME-v$VERSION.iso (bootable ISO)
+- $PROJECT_NAME-v$VERSION.sha256 (SHA256 checksum)
+- $PROJECT_NAME-v$VERSION.md5 (MD5 checksum)
+
+Technical Specifications:
+- Base Distribution: Debian Testing
+- Boot Support: Hybrid UEFI/Legacy BIOS
+- Filesystem: SquashFS + ISO9660
+- Package Manager: apt
+- Init System: systemd
+
+Features:
+- Debian Installer with GUI
+- Full firmware support
+- Security configurations
+- Memtest86+ memory testing
+
+Build Status: SUCCESSFUL
+
+Next Steps:
+1. Test ISO on target hardware
+2. Validate installation process
+3. Apply KNEL-Football security configurations
+4. Deploy to production environment
+
+ISO Information:
+Type: Hybrid (UEFI + Legacy BIOS compatible)
+Checksum: SHA256 (see .sha256 file)
+
+Contact: KNEL-Football IT Security Team
+Generated: $(date)
+REPORT
+        
+        echo '✓ Build report created'
+        echo '✓ All artifacts copied to /output/'
+        
+        echo ''
+        echo '=== BUILD RESULTS ==='
+        ls -la /output/
+        
+        # Display ISO info
+        if [ -f \"/output/$FINAL_ISO\" ]; then
+            echo ''
+            echo 'ISO Details:'
+            echo \"File: $FINAL_ISO\"
+            echo \"Size: $(du -h \"/output/$FINAL_ISO\" | cut -f1)\"
+            echo \"SHA256: $(cat \"/output/${FINAL_ISO}.sha256\" | cut -d' ' -f1)\"
+        fi
+        
+    else
+        echo '✗ No ISO file found'
+        exit 1
+    fi
+else
+    echo '✗ Build failed or timed out'
+    exit 1
+fi
+"
+
+# Check if build succeeded
+echo ""
+echo "=== BUILD COMPLETION CHECK ==="
+
+if [ -f "output/$PROJECT_NAME-v$VERSION.iso" ]; then
+  echo "✓ BUILD SUCCESSFUL!"
+  echo "✓ ISO created: $PROJECT_NAME-v$VERSION.iso"
+  echo "✓ Size: $(du -h "output/$PROJECT_NAME-v$VERSION.iso" | cut -f1)"
+  echo "✓ SHA256: $(cat "output/$PROJECT_NAME-v$VERSION.sha256" | cut -d' ' -f1)"
+
+  echo ""
+  echo "=== FINAL ARTIFACTS ==="
+  ls -lah output/
+
+  echo ""
+  echo "=== SUCCESS ==="
+  echo "KNEL-Football Secure OS built successfully in Docker!"
+  echo "All artifacts available in ./output/"
+  echo "No host system modifications were performed."
+
+  exit 0
+else
+  echo "✗ BUILD FAILED"
+  echo "Check Docker container output for errors"
+  echo "Artifacts in output:"
+  ls -lah output/ 2>/dev/null || echo "No artifacts created"
+
+  exit 1
+fi

src/firewall-setup.sh

@@ -4,26 +4,26 @@ set -euo pipefail
 
 # Function to parse WireGuard endpoint
 parse_wg_endpoint() {
-    local wg_config="${1:-/etc/wireguard/wg0.conf}"
-    
-    if [[ ! -f "$wg_config" ]]; then
-        echo "Error: WireGuard config not found at $wg_config"
-        return 1
-    fi
-    
-    grep -oP 'Endpoint = \K[0-9.]+:[0-9]+' "$wg_config" || {
-        echo "Error: Could not parse endpoint from WireGuard config"
-        return 1
-    }
+  local wg_config="${1:-/etc/wireguard/wg0.conf}"
+
+  if [[ ! -f $wg_config ]]; then
+    echo "Error: WireGuard config not found at $wg_config"
+    return 1
+  fi
+
+  grep -oP 'Endpoint = \K[0-9.]+:[0-9]+' "$wg_config" || {
+    echo "Error: Could not parse endpoint from WireGuard config"
+    return 1
+  }
 }
 
 # Function to generate nftables rules
 generate_nftables_rules() {
-    local endpoint="$1"
-    local ip="${endpoint%:*}"
-    local port="${endpoint#*:}"
-    
-    cat << EOF
+  local endpoint="$1"
+  local ip="${endpoint%:*}"
+  local port="${endpoint#*:}"
+
+  cat <<EOF
 #!/usr/sbin/nft -f
 # Secure firewall rules for WireGuard-only access
 flush ruleset
@@ -51,31 +51,31 @@ EOF
 
 # Function to apply firewall configuration
 apply_firewall() {
-    local wg_config="${1:-/etc/wireguard/wg0.conf}"
-    
-    if [[ -f "$wg_config" ]]; then
-        endpoint=$(parse_wg_endpoint "$wg_config")
-        if [[ -n "$endpoint" ]]; then
-            generate_nftables_rules "$endpoint" > /etc/nftables.conf
-            systemctl enable nftables
-            systemctl restart nftables
-            echo "Firewall configured for endpoint: $endpoint"
-        else
-            echo "Warning: Could not parse WireGuard endpoint, using default deny policy"
-        fi
+  local wg_config="${1:-/etc/wireguard/wg0.conf}"
+
+  if [[ -f $wg_config ]]; then
+    endpoint=$(parse_wg_endpoint "$wg_config")
+    if [[ -n $endpoint ]]; then
+      generate_nftables_rules "$endpoint" >/etc/nftables.conf
+      systemctl enable nftables
+      systemctl restart nftables
+      echo "Firewall configured for endpoint: $endpoint"
     else
-        echo "Warning: WireGuard config not found, using default deny policy"
+      echo "Warning: Could not parse WireGuard endpoint, using default deny policy"
     fi
+  else
+    echo "Warning: WireGuard config not found, using default deny policy"
+  fi
 }
 
 # Main setup
 main() {
-    echo "Setting up dynamic firewall..."
-    apply_firewall
-    echo "Firewall setup completed."
+  echo "Setting up dynamic firewall..."
+  apply_firewall
+  echo "Firewall setup completed."
 }
 
 # Run main if script is executed directly
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+  main "$@"
+fi

src/run-new.sh

@@ -0,0 +1,291 @@
+#!/bin/bash
+# Enhanced version of the original run.sh script with explicit container management
+set -euo pipefail
+
+# Project metadata
+readonly PROJECT_NAME="KNEL Football"
+readonly VERSION="1.0.0"
+
+# Configuration
+readonly DOCKER_IMAGE="${DOCKER_IMAGE:-knel-football-dev:latest}" # Using required knel-football-dev image
+readonly CONTAINER_PREFIX="knel-football"
+readonly PROXY_ENABLED="${PROXY_ENABLED:-true}"
+readonly PROXY_URL="${PROXY_URL:-http://10.0.0.1:3128}"
+
+# Source utility functions
+source "$(dirname "$0")/lib/docker.sh"
+
+# Logging function
+log() {
+  echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*"
+}
+
+# Usage information
+usage() {
+  cat <<EOF
+$PROJECT_NAME v$VERSION
+Containerized ISO build and security hardening framework
+
+USAGE:
+    $0 [OPTIONS] [COMMAND]
+
+COMMANDS:
+    build           Build Docker image
+    lint            Run lint checks
+    test            Run tests
+    test:unit       Run unit tests
+    test:integration Run integration tests
+    test:functional  Run functional tests
+    shell           Start interactive shell
+    clean           Clean build artifacts
+    iso             Build ISO image
+    secure          Generate security configuration
+    deploy          Prepare deployment package
+    help            Show this help message
+
+OPTIONS:
+    -v, --verbose   Enable verbose output
+    -q, --quiet     Suppress non-error output
+    -e, --env       Set environment variable (can be multiple)
+    --no-cache      Build without using cache
+    --proxy         Use proxy for network operations
+    --no-proxy      Disable proxy for network operations
+
+ENVIRONMENT VARIABLES:
+    DOCKER_IMAGE    Docker image to use (default: knel-football-dev:latest)
+    PROXY_ENABLED   Enable/disable proxy (default: true)
+    PROXY_URL       Proxy URL (default: http://10.0.0.1:3128)
+
+EXAMPLES:
+    $0 build
+    $0 lint
+    $0 test
+    $0 shell
+    $0 iso
+    $0 clean
+    $0 -v --no-proxy test:unit
+
+For more information, see: README.md
+EOF
+}
+
+# Parse command line arguments
+VERBOSE=false
+QUIET=false
+NO_CACHE=false
+USE_PROXY=$PROXY_ENABLED
+ENV_VARS=()
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+  -v | --verbose)
+    VERBOSE=true
+    QUIET=false
+    shift
+    ;;
+  -q | --quiet)
+    QUIET=true
+    VERBOSE=false
+    shift
+    ;;
+  -e | --env)
+    ENV_VARS+=("$2")
+    shift 2
+    ;;
+  --no-cache)
+    NO_CACHE=true
+    shift
+    ;;
+  --proxy)
+    USE_PROXY=true
+    shift
+    ;;
+  --no-proxy)
+    USE_PROXY=false
+    shift
+    ;;
+  -h | --help | help)
+    usage
+    exit 0
+    ;;
+  build | lint | test | test:unit | test:integration | test:functional | shell | clean | iso | secure | deploy)
+    COMMAND="$1"
+    shift
+    break
+    ;;
+  *)
+    echo "Unknown option: $1"
+    usage
+    exit 1
+    ;;
+  esac
+done
+
+# Set default command
+COMMAND="${COMMAND:-help}"
+
+# Logging with verbosity control
+log_info() {
+  if [ "$QUIET" = false ]; then
+    log "INFO: $*"
+  fi
+}
+
+log_error() {
+  log "ERROR: $*" >&2
+}
+
+log_debug() {
+  if [ "$VERBOSE" = true ]; then
+    log "DEBUG: $*"
+  fi
+}
+
+# Container management
+run_with_container() {
+  local cmd="$1"
+  local container_name="${CONTAINER_PREFIX}-${cmd}"
+  shift
+
+  log_info "Starting container: $container_name"
+  log_debug "Command: $*"
+
+  # Build environment arguments
+  local env_args=()
+  for env_var in "${ENV_VARS[@]}"; do
+    env_args+=("-e" "$env_var")
+  done
+
+  if [ "$USE_PROXY" = true ]; then
+    env_args+=("-e" "http_proxy=$PROXY_URL")
+    env_args+=("-e" "https_proxy=$PROXY_URL")
+  fi
+
+  # Run container with explicit name and environment
+  docker run --name "$container_name" \
+    --env-file <(grep -v '^#' "$(dirname "$0")/.env" 2>/dev/null || true) \
+    "${env_args[@]}" \
+    -v "$(pwd)":/workspace:ro \
+    -v "$(pwd)/tmp":/build \
+    -v "$(pwd)/output":/output \
+    -e TZ="UTC" \
+    -e DEBIAN_FRONTEND="noninteractive" \
+    -e LC_ALL="C" \
+    --rm \
+    "$DOCKER_IMAGE" \
+    "$@"
+}
+
+# Main command handlers
+cmd_build() {
+  log_info "Building Docker image: $DOCKER_IMAGE"
+
+  local build_args=()
+  if [ "$NO_CACHE" = true ]; then
+    build_args+=("--no-cache")
+  fi
+
+  if [ "$USE_PROXY" = true ]; then
+    build_args+=("--build-arg" "http_proxy=$PROXY_URL")
+    build_args+=("--build-arg" "https_proxy=$PROXY_URL")
+  fi
+
+  docker build "${build_args[@]}" -t "$DOCKER_IMAGE" "$(dirname "$0")"
+}
+
+cmd_lint() {
+  log_info "Running lint checks"
+  run_with_container "lint" make lint
+}
+
+cmd_test() {
+  log_info "Running all tests"
+  run_with_container "test" make test
+}
+
+cmd_test_unit() {
+  log_info "Running unit tests"
+  run_with_container "test-unit" make test-unit
+}
+
+cmd_test_integration() {
+  log_info "Running integration tests"
+  run_with_container "test-integration" make test-integration
+}
+
+cmd_test_functional() {
+  log_info "Running functional tests"
+  run_with_container "test-functional" make test-functional
+}
+
+cmd_shell() {
+  log_info "Starting interactive shell"
+  run_with_container "shell" /bin/bash
+}
+
+cmd_clean() {
+  log_info "Cleaning build artifacts"
+  rm -rf "$(dirname "$0")/tmp"
+  mkdir -p "$(dirname "$0")/tmp"
+  log_info "Cleanup completed"
+}
+
+cmd_iso() {
+  log_info "Building ISO image"
+  run_with_container "iso" make iso
+}
+
+cmd_secure() {
+  log_info "Generating security configuration"
+  run_with_container "secure" make secure
+}
+
+cmd_deploy() {
+  log_info "Preparing deployment package"
+  run_with_container "deploy" make deploy
+}
+
+# Execute command
+case "$COMMAND" in
+build)
+  cmd_build
+  ;;
+lint)
+  cmd_lint
+  ;;
+test)
+  cmd_test
+  ;;
+test:unit)
+  cmd_test_unit
+  ;;
+test:integration)
+  cmd_test_integration
+  ;;
+test:functional)
+  cmd_test_functional
+  ;;
+shell)
+  cmd_shell
+  ;;
+clean)
+  cmd_clean
+  ;;
+iso)
+  cmd_iso
+  ;;
+secure)
+  cmd_secure
+  ;;
+deploy)
+  cmd_deploy
+  ;;
+help)
+  usage
+  ;;
+*)
+  log_error "Unknown command: $COMMAND"
+  usage
+  exit 1
+  ;;
+esac

src/run.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# KNEL-Football ISO Builder - Host Wrapper
+# This script orchestrates the Docker-based build process
+# Copyright © 2026 Known Element Enterprises LLC
+
+set -euo pipefail
+
+# Configuration variables
+readonly DOCKER_IMAGE="knel-football-dev:latest" # Using required knel-football-dev image
+readonly SCRIPT_DIR
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly OUTPUT_DIR="${SCRIPT_DIR}/output"
+readonly BUILD_DIR="${SCRIPT_DIR}/tmp"
+
+# Create output and build directories if they don't exist
+mkdir -p "${OUTPUT_DIR}" "${BUILD_DIR}"
+
+# Function to show usage
+usage() {
+  echo "Usage: $0 [command]"
+  echo "Commands:"
+  echo "  build     Build the secure ISO"
+  echo "  test      Run all tests"
+  echo "  lint      Run linting checks"
+  echo "  clean     Clean build artifacts"
+  echo "  shell     Interactive shell in build container"
+  exit 1
+}
+
+# Main execution logic
+main() {
+  local command="${1:-build}"
+
+  case "${command}" in
+  build)
+    echo "Building KNEL-Football secure ISO..."
+    docker run --rm \
+      -v "${SCRIPT_DIR}:/workspace:ro" \
+      -v "${OUTPUT_DIR}:/output" \
+      -v "${BUILD_DIR}:/build" \
+      -e TZ="UTC" \
+      -e DEBIAN_FRONTEND="noninteractive" \
+      -e LC_ALL="C" \
+      "${DOCKER_IMAGE}" \
+      /workspace/src/build-iso.sh
+    ;;
+  test)
+    echo "Running KNEL-Football test suite..."
+    docker run --rm \
+      -v "${SCRIPT_DIR}:/workspace:ro" \
+      -v "${BUILD_DIR}:/tmp" \
+      "${DOCKER_IMAGE}" \
+      bats -r /workspace/tests/
+    ;;
+  lint)
+    echo "Running linting checks..."
+    docker run --rm \
+      -v "${SCRIPT_DIR}:/workspace:ro" \
+      "${DOCKER_IMAGE}" \
+      shellcheck /workspace/src/*.sh /workspace/config/hooks/*/*.sh
+    ;;
+  clean)
+    echo "Cleaning build artifacts..."
+    rm -rf "${OUTPUT_DIR:?}"/*
+    rm -rf "${BUILD_DIR:?}"/*
+    ;;
+  shell)
+    echo "Starting interactive shell..."
+    docker run --rm -it \
+      -v "${SCRIPT_DIR}:/workspace:ro" \
+      -v "${OUTPUT_DIR}:/output" \
+      -v "${BUILD_DIR}:/build" \
+      -e TZ="UTC" \
+      -e DEBIAN_FRONTEND="noninteractive" \
+      -e LC_ALL="C" \
+      "${DOCKER_IMAGE}" \
+      bash
+    ;;
+  *)
+    usage
+    ;;
+  esac
+}
+
+main "$@"

src/security-hardening.sh

@@ -4,9 +4,9 @@ set -euo pipefail
 
 # Function to create WiFi module blacklist
 create_wifi_blacklist() {
-    local output_file="${1:-/etc/modprobe.d/blacklist-wifi.conf}"
-    
-    cat > "$output_file" << 'EOF'
+  local output_file="${1:-/etc/modprobe.d/blacklist-wifi.conf}"
+
+  cat >"$output_file" <<'EOF'
 # WiFi module blacklisting
 blacklist cfg80211
 blacklist mac80211
@@ -15,15 +15,15 @@ blacklist iwlwifi
 blacklist ath9k
 blacklist rt73usb
 EOF
-    
-    echo "WiFi blacklist created at $output_file"
+
+  echo "WiFi blacklist created at $output_file"
 }
 
 # Function to create Bluetooth module blacklist
 create_bluetooth_blacklist() {
-    local output_file="${1:-/etc/modprobe.d/blacklist-bluetooth.conf}"
-    
-    cat > "$output_file" << 'EOF'
+  local output_file="${1:-/etc/modprobe.d/blacklist-bluetooth.conf}"
+
+  cat >"$output_file" <<'EOF'
 # Bluetooth module blacklisting
 blacklist btusb
 blacklist bluetooth
@@ -31,15 +31,15 @@ blacklist btrtl
 blacklist btintel
 blacklist btbcm
 EOF
-    
-    echo "Bluetooth blacklist created at $output_file"
+
+  echo "Bluetooth blacklist created at $output_file"
 }
 
 # Function to configure SSH
 configure_ssh() {
-    local output_file="${1:-/etc/ssh/sshd_config}"
-    
-    cat > "$output_file" << 'EOF'
+  local output_file="${1:-/etc/ssh/sshd_config}"
+
+  cat >"$output_file" <<'EOF'
 # SSH Security Configuration
 Protocol 2
 PermitRootLogin no
@@ -52,15 +52,15 @@ MaxAuthTries 3
 ClientAliveInterval 300
 ClientAliveCountMax 2
 EOF
-    
-    echo "SSH configuration created at $output_file"
+
+  echo "SSH configuration created at $output_file"
 }
 
 # Function to configure password policy
 configure_password_policy() {
-    local output_file="${1:-/etc/security/pwquality.conf}"
-    
-    cat > "$output_file" << 'EOF'
+  local output_file="${1:-/etc/security/pwquality.conf}"
+
+  cat >"$output_file" <<'EOF'
 # Password quality requirements
 minlen = 14
 dcredit = -1
@@ -72,29 +72,29 @@ maxrepeat = 3
 usercheck = 1
 dictcheck = 1
 EOF
-    
-    echo "Password policy configured at $output_file"
+
+  echo "Password policy configured at $output_file"
 }
 
 # Function to configure system limits
 configure_system_limits() {
-    local output_file="${1:-/etc/security/limits.d/security.conf}"
-    
-    cat > "$output_file" << 'EOF'
+  local output_file="${1:-/etc/security/limits.d/security.conf}"
+
+  cat >"$output_file" <<'EOF'
 # System security limits
 * hard core 0
 * soft nproc 1024
 * hard nproc 2048
 EOF
-    
-    echo "System limits configured at $output_file"
+
+  echo "System limits configured at $output_file"
 }
 
 # Function to configure audit rules
 configure_audit_rules() {
-    local output_file="${1:-/etc/audit/rules.d/audit.rules}"
-    
-    cat > "$output_file" << 'EOF'
+  local output_file="${1:-/etc/audit/rules.d/audit.rules}"
+
+  cat >"$output_file" <<'EOF'
 # Audit rules for security compliance
 -w /etc/passwd -p wa -k identity
 -w /etc/shadow -p wa -k identity
@@ -104,32 +104,32 @@ configure_audit_rules() {
 -w /var/log/secure -p wa -k log_secure
 -w /etc/wireguard/ -p wa -k wireguard_config
 EOF
-    
-    echo "Audit rules configured at $output_file"
+
+  echo "Audit rules configured at $output_file"
 }
 
 # Function to apply all security configurations
 apply_security_hardening() {
-    echo "Applying security hardening..."
-    
-    create_wifi_blacklist
-    create_bluetooth_blacklist
-    configure_ssh
-    configure_password_policy
-    configure_system_limits
-    configure_audit_rules
-    
-    echo "Security hardening completed."
+  echo "Applying security hardening..."
+
+  create_wifi_blacklist
+  create_bluetooth_blacklist
+  configure_ssh
+  configure_password_policy
+  configure_system_limits
+  configure_audit_rules
+
+  echo "Security hardening completed."
 }
 
 # Main execution
 main() {
-    echo "Starting KNEL-Football security hardening..."
-    apply_security_hardening
-    echo "Security hardening completed successfully!"
+  echo "Starting KNEL-Football security hardening..."
+  apply_security_hardening
+  echo "Security hardening completed successfully!"
 }
 
 # Run main if script is executed directly
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+  main "$@"
+fi