========================================================================
                      MUPPY 10 SYSTEM HANDBOOK
========================================================================

------------------------------------------------------------------------
CHAPTER 1: WHAT IS MUPPY 10?
------------------------------------------------------------------------
Muppy 10 is a ultra-lean, custom-built, Debian-based Linux live distribution 
designed to run entirely in RAM. Weighing in at approximately 470 MB, it 
provides a lightweight X11 window management environment (powered by IceWM or 
a custom Vala/C window manager like `mu-wm`) coupled with Picom compositing 
and customized system HUDs (`tech-hud`).

Key Features:
- Pure RAM Execution: System files are loaded into RAM during boot for 
  blazing-fast performance and zero disk wear.
- Minimal Footprint: Built directly from Debian stable using `mmdebstrap` 
  without unnecessary bloat or standard desktop environment overhead.
- Dual-Boot Ready: Can easily run alongside host OS installations like 
  Linux Mint 22.3 without touching existing partitions.
- Failsafe Modular Build System: Allows quick live modifications via chroot 
  and fast ISO repacking within seconds.


------------------------------------------------------------------------
CHAPTER 2: EXTENDING & CUSTOMIZING MUPPY (SYNAPTIC / APT & MOUNTING ISOS)
------------------------------------------------------------------------

2.1 MANAGING PACKAGES WITH APT & SYNAPTIC
-----------------------------------------
Muppy 10 comes pre-installed with standard Debian package management tools 
including `apt` and the graphical `synaptic` package manager.

To install new software inside a running Muppy session or inside the chroot:

  - Using the Terminal:
      sudo apt update
      sudo apt install <package-name>

  - Using Graphical Synaptic:
      Launch Synaptic from the menu or terminal (`sudo synaptic`), click 
      "Reload" to update package indexes, search for desired software, 
      mark for installation, and click "Apply".

Note: Any packages installed during a standard RAM session will disappear 
upon reboot unless persistence is configured or changes are committed 
directly into the build environment (see Chapter 6).


2.2 HOW TO MOUNT AND INSPECT AN ISO FILE
----------------------------------------
If you want to extract files, check contents, or copy the live SquashFS 
from an existing `muppy10-amd64.iso` file on your host system without 
booting it, you can mount the ISO file as a loop device:

1. Create a mount directory:
   sudo mkdir -p /mnt/iso

2. Mount the ISO in read-only mode:
   sudo mount -o loop /path/to/muppy10-amd64.iso /mnt/iso

3. Inspect or copy files:
   ls -la /mnt/iso
   ls -la /mnt/iso/live/    # Contains filesystem.squashfs

4. Unmount when finished:
   sudo umount /mnt/iso


------------------------------------------------------------------------
CHAPTER 3: RUNNING MUPPY 10 (QEMU & PC RAM BOOT)
------------------------------------------------------------------------

3.1 STARTING IN A LOCAL QEMU VIRTUAL MACHINE
--------------------------------------------
To test your build instantly inside a virtual machine without rebooting 
your hardware:

1. Install QEMU on your host:
   sudo apt update
   sudo apt install -y qemu-system-x86

2. Launch the ISO in QEMU (with 2 GB RAM and KVM hardware acceleration):
   qemu-system-x86_64 -m 2048 -enable-kvm -cdrom muppy10-amd64.iso


3.2 STARTING ON YOUR PC FROM A LIVE USB (RAM MODE)
--------------------------------------------------
To boot Muppy 10 on bare-metal hardware using a bootable USB flash drive:

1. Write the ISO to a USB flash drive (replace `/dev/sdX` with your drive):
   sudo dd if=muppy10-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync

2. Insert the USB drive into your target PC and boot into your system BIOS/UEFI.
3. Select the USB drive from the boot menu.
4. Select "Muppy 10 (RAM Mode)" in GRUB.

System Behavior in RAM Mode:
The entire root filesystem (`filesystem.squashfs`) is uncompressed into system 
RAM. The USB drive can be safely removed after booting. All temporary files, 
browser histories, and system tweaks remain strictly in RAM and are completely 
wiped when power is turned off.


------------------------------------------------------------------------
CHAPTER 4: INSTALLING MUPPY TO YOUR PC (RAM MODE / NON-PERSISTENT)
------------------------------------------------------------------------
If you have a host OS like Linux Mint 22.3 installed on your Mini-PC or SSD, 
you can install Muppy 10 directly onto a dedicated partition (or external USB) 
so it boots from local storage into RAM without needing a USB installer stick.

HOW IT WORKS:
GRUB loads the kernel and initrd directly from your local disk, uncompresses 
`filesystem.squashfs` into system RAM, and runs Muppy at full RAM speed. 
Changes made during the session are NOT saved back to the disk.

STEP 1: PREPARE THE TARGET PARTITION (USING GPARTED)
----------------------------------------------------
1. Open GParted (`sudo gparted`).
2. Select your target disk (e.g., `/dev/sda` or external drive `/dev/sdb`).
3. Create/format a partition with the following parameters:
   - Filesystem: `ext4`
   - Label: `MUPPY10`
   - Flags: Set `boot` (or `legacy_boot`) on the partition.

STEP 2: COPY MUPPY LIVE FILES TO THE TARGET PARTITION
------------------------------------------------------
1. Mount your new partition:
   sudo mkdir -p /mnt/muppy
   sudo mount /dev/sdb1 /mnt/muppy    # Replace /dev/sdb1 with your partition

2. Create the required directory structure:
   sudo mkdir -p /mnt/muppy/live

3. Copy the live kernel, initrd, and SquashFS files:
   # You can copy directly from your build directory or a mounted ISO:
   sudo cp -av /tmp/muppy10-build/iso/live/filesystem.squashfs /mnt/muppy/live/
   sudo cp -av /tmp/muppy10-build/iso/vmlinuz /mnt/muppy/
   sudo cp -av /tmp/muppy10-build/iso/initrd.img /mnt/muppy/

4. Unmount the partition:
   sudo umount /mnt/muppy

STEP 3: INTEGRATE WITH LINUX MINT GRUB
--------------------------------------
1. Open `/etc/grub.d/40_custom` in your Linux Mint host text editor:
   sudo geany /etc/grub.d/40_custom

2. Add the following entry at the bottom of the file:

   menuentry "Muppy 10 Live (RAM Mode from SSD)" {
       search --no-floppy --set=root --label MUPPY10
       linux /vmlinuz boot=live live-media-path=/live keyboard-layouts=us quiet splash
       initrd /initrd.img
   }

3. Update GRUB configuration:
   sudo update-grub

Reboot your PC and select "Muppy 10 Live (RAM Mode from SSD)" from the GRUB menu.


------------------------------------------------------------------------
CHAPTER 5: INSTALLING MUPPY TO YOUR PC (WITH PERSISTENT STORAGE)
------------------------------------------------------------------------
If you want Muppy 10 to act as a fully installed OS that saves your files, 
installed packages, user configurations, and scripts across reboots, configure 
Debian `live-boot` persistence.

HOW IT WORKS:
Muppy still boots the base SquashFS into RAM for performance, but an overlay 
filesystem continuously writes and reads system modifications to an `ext4` 
persistence partition on disk.

STEP 1: PREPARE PERSISTENCE PARTITION
-------------------------------------
1. Open GParted (`sudo gparted`).
2. Format a partition with `ext4`.
3. CRITICAL: Set the Partition Label to exactly: `persistence`

STEP 2: CREATE PERSISTENCE CONFIGURATION FILE
---------------------------------------------
1. Mount the persistence partition:
   sudo mkdir -p /mnt/persistence
   sudo mount /dev/sdb2 /mnt/persistence    # Replace with your partition

2. Write the overlay rule into `persistence.conf`:
   echo "/ union" | sudo tee /mnt/persistence/persistence.conf

   *(Explanation: `/ union` directs the system to merge all changes made across 
   the entire root filesystem `/` directly onto this partition).*

3. Unmount the partition:
   sudo umount /mnt/persistence

STEP 3: ADD PERSISTENT BOOT ENTRY TO GRUB
-----------------------------------------
1. Open `/etc/grub.d/40_custom` on your Linux Mint host:
   sudo geany /etc/grub.d/40_custom

2. Add a new menu entry containing the `persistence` parameter:

   menuentry "Muppy 10 (Persistent Mode)" {
       search --no-floppy --set=root --label MUPPY10
       linux /vmlinuz boot=live live-media-path=/live persistence keyboard-layouts=us quiet splash
       initrd /initrd.img
   }

3. Update GRUB:
   sudo update-grub

Now, whenever you boot into "Muppy 10 (Persistent Mode)", any file created 
in `/home/live`, any configuration changed, or any package installed via 
`apt` will automatically persist across reboots!


------------------------------------------------------------------------
CHAPTER 6: CREATING & REBUILDING YOUR OWN ISO
------------------------------------------------------------------------

6.1 PREREQUISITES FOR THE HOST SYSTEM
-------------------------------------
Run the following command on your Linux Mint/Debian host to install all 
required build tools:

   sudo apt update
   sudo apt install -y mmdebstrap squashfs-tools xorriso grub-pc-bin debian-archive-keyring

6.2 PREPARING CUSTOM BINARIES (OPTIONAL)
----------------------------------------
Place compiled Vala/C binaries (`mu-wm`, `tech-hud`) into `./custom-bin`:

   mkdir -p ./custom-bin
   cp /path/to/your/mu-wm ./custom-bin/
   cp /path/to/your/tech-hud ./custom-bin/

6.3 FULL INITIAL BUILD PROCESS
------------------------------
Run `build-muppy10.sh` as root to assemble the chroot and generate the ISO:

   chmod +x build-muppy10.sh enter-chroot.sh rebuild-iso.sh
   sudo ./build-muppy10.sh

6.4 FAILSAFE MODIFY & FAST-REBUILD WORKFLOW
-------------------------------------------
To edit the OS without re-downloading Debian packages:

1. Enter Chroot:
   sudo ./enter-chroot.sh
   (Make your changes, install packages, edit configs, then type `exit`).

2. Rebuild ISO in seconds:
   sudo ./rebuild-iso.sh

6.5 BACKING UP YOUR BUILD FROM /tmp
-----------------------------------
Since `/tmp/muppy10-build` is cleared on host reboot, save your chroot state:

   sudo cp -a /tmp/muppy10-build ~/muppy10-build-backup

To restore after a reboot:
   sudo mkdir -p /tmp/muppy10-build
   sudo cp -a ~/muppy10-build-backup/* /tmp/muppy10-build/
========================================================================