Address code review feedback: clarify image capabilities

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>

.github/workflows/build-image.yml

@@ -98,46 +98,46 @@ jobs:
           
           # Create a README for the release
           cat > release/README.txt << 'EOF'
-          SparkOS Bootable Disk Image
+          SparkOS Filesystem Disk Image
-          ===========================
+          ==============================
           
-          This package contains a compressed bootable disk image for SparkOS.
+          This package contains a compressed ext4 filesystem image with SparkOS.
           
           Files:
           - sparkos.img.gz - Compressed ext4 filesystem image (512MB)
           
+          What's Included:
+          ---------------
+          The image contains:
+          - SparkOS init system (/sbin/init)
+          - Basic filesystem structure (FHS compliant)
+          - Configuration files
+          
+          Note: This is a minimal filesystem image. For full booting, you need:
+          - Linux kernel (install to /boot/vmlinuz)
+          - Busybox (install to /bin/busybox)
+          - Bootloader (GRUB or syslinux)
+          
           Quick Start:
           -----------
           
           1. Decompress the image:
              gunzip sparkos.img.gz
           
-          2. Write to a USB drive (Linux):
+          2. Mount and inspect:
+             sudo mount -o loop sparkos.img /mnt
+             ls -la /mnt
+             sudo umount /mnt
+          
+          3. Or write to USB for testing (Linux - BE CAREFUL!):
              sudo dd if=sparkos.img of=/dev/sdX bs=4M status=progress
              sync
              
              WARNING: Replace /dev/sdX with your actual USB drive device.
                       This will DESTROY all data on the target drive!
           
-          3. Or mount and inspect:
+          Documentation:
-             sudo mount -o loop sparkos.img /mnt
+          -------------
-             ls -la /mnt
-             sudo umount /mnt
-          
-          Image Contents:
-          --------------
-          The image contains:
-          - SparkOS init system (/sbin/init)
-          - Basic filesystem structure (FHS compliant)
-          - Configuration files
-          
-          To make fully bootable:
-          ----------------------
-          The image needs additional components for booting:
-          1. Linux kernel (install to /boot/vmlinuz)
-          2. Busybox (install to /bin/busybox)
-          3. Bootloader (GRUB or syslinux)
-          
           See the full documentation at:
           https://github.com/johndoe6345789/SparkOS
           
@@ -148,9 +148,9 @@ jobs:
           EOF
           
           # Create a ZIP with the image and README
-          cd release
+          cd release || exit 1
           zip sparkos-image.zip sparkos.img.gz README.txt
-          cd ..
+          cd .. || exit 1
           
           echo "Release package created!"
           ls -lh release/
@@ -174,24 +174,45 @@ jobs:
           body: |
             # SparkOS Disk Image Release ${{ github.ref_name }}
             
-            This release includes a bootable disk image that can be written to USB drives.
+            This release includes a filesystem disk image with the SparkOS init system.
             
             ## What's Included
             
             - **sparkos-image.zip**: Complete package with image and README
-            - **sparkos.img.gz**: Compressed disk image (512MB ext4 filesystem)
+            - **sparkos.img.gz**: Compressed ext4 filesystem image (512MB)
+            
+            ## What This Image Contains
+            
+            The disk image includes:
+            - ✅ SparkOS init system binary (statically linked)
+            - ✅ FHS-compliant filesystem structure
+            - ✅ Basic configuration files
+            
+            **Note**: This is a minimal filesystem image. For full booting, you'll need to add:
+            - Linux kernel
+            - Busybox utilities
+            - Bootloader (GRUB or syslinux)
+            
+            See the [documentation](https://github.com/johndoe6345789/SparkOS#creating-a-bootable-image) for details.
             
             ## Quick Start
             
-            ### Download and Write to USB
+            ### Mount and Inspect
             
             ```bash
-            # Download the compressed image
+            # Download and decompress
             wget https://github.com/johndoe6345789/SparkOS/releases/download/${{ github.ref_name }}/sparkos.img.gz
-            
-            # Decompress
             gunzip sparkos.img.gz
             
+            # Mount and inspect
+            sudo mount -o loop sparkos.img /mnt
+            ls -la /mnt
+            sudo umount /mnt
+            ```
+            
+            ### Write to USB (Testing)
+            
+            ```bash
             # Write to USB drive (Linux - BE CAREFUL!)
             sudo dd if=sparkos.img of=/dev/sdX bs=4M status=progress
             sudo sync
@@ -199,15 +220,6 @@ jobs:
             
             **⚠️ WARNING**: Replace `/dev/sdX` with your actual USB device. This will erase all data on the target drive!
             
-            ### Inspect the Image
-            
-            ```bash
-            # Mount and inspect
-            sudo mount -o loop sparkos.img /mnt
-            ls -la /mnt
-            sudo umount /mnt
-            ```
-            
             ## Docker Image
             
             A Docker image is also available:

Dockerfile.image

@@ -54,16 +54,23 @@ RUN mkdir -p /output && \
     echo "spark:x:1000:" >> /mnt/img/etc/group && \
     # Create README
     cat > /mnt/img/README.txt << 'EOF' && \
-SparkOS Minimal Image
+SparkOS Minimal Filesystem Image
 
-This is a minimal SparkOS filesystem image containing the init system.
+This is a minimal ext4 filesystem image containing the SparkOS init system.
+This is NOT a fully bootable image - it requires additional components.
 
-To make this fully bootable, you need to:
+What's included:
-1. Install a Linux kernel to /boot/vmlinuz
+- SparkOS init binary (/sbin/init)
-2. Install busybox to /bin/busybox and create symlinks
+- Basic FHS-compliant directory structure
-3. Install a bootloader (GRUB or syslinux)
+- Basic configuration files
 
-This image can be mounted and the init binary extracted:
+To make this fully bootable, you need to add:
+1. Linux kernel (install to /boot/vmlinuz)
+2. Busybox (install to /bin/busybox and create symlinks)
+3. Bootloader (GRUB or syslinux)
+4. Required libraries (if using dynamically linked binaries)
+
+This image can be mounted to extract the init binary or inspect the structure:
   sudo mount -o loop sparkos.img /mnt
   cp /mnt/sbin/init ./
   sudo umount /mnt

README.md

@@ -45,9 +45,9 @@ To create bootable images (optional):
 
 ## Quick Start
 
-### Using Pre-built Disk Image (Easiest for USB Boot)
+### Using Pre-built Disk Image (Easiest for USB/Testing)
 
-Download the bootable disk image from the [GitHub Releases page](https://github.com/johndoe6345789/SparkOS/releases):
+Download the filesystem image from the [GitHub Releases page](https://github.com/johndoe6345789/SparkOS/releases):
 
 ```bash
 # Download the disk image (replace VERSION with actual version, e.g., v1.0.0)
@@ -56,18 +56,24 @@ wget https://github.com/johndoe6345789/SparkOS/releases/download/VERSION/sparkos
 # Decompress the image
 gunzip sparkos.img.gz
 
-# Write to USB drive (Linux - BE CAREFUL!)
+# Mount and inspect
+sudo mount -o loop sparkos.img /mnt
+ls -la /mnt
+sudo umount /mnt
+
+# Or write to USB drive for testing (Linux - BE CAREFUL!)
 sudo dd if=sparkos.img of=/dev/sdX bs=4M status=progress
 sudo sync
 ```
 
 **⚠️ WARNING**: Replace `/dev/sdX` with your actual USB device (e.g., `/dev/sdb`). This will **DESTROY ALL DATA** on the target drive!
 
+**Note**: The disk image contains the init system and filesystem structure but requires additional components (kernel, busybox, bootloader) for full booting. See [Creating a Bootable Image](#creating-a-bootable-image) section.
+
 The disk image includes:
 - Pre-compiled init binary
 - Basic filesystem structure (FHS compliant)
 - Configuration files
-- Ready to write to USB drives
 
 ### Using Pre-built Binary Package