========================================================================
                      MUPPY 10 BUILD INSTRUCTIONS
========================================================================

OVERVIEW & ARCHITECTURE:
------------------------
This build system creates a minimal, fast Debian-based live ISO ("Muppy 10") 
in RAM mode. The build environment lives in `/tmp/muppy10-build`. 

- `/tmp/muppy10-build/chroot`: The uncompressed root filesystem of your live OS.
- `/tmp/muppy10-build/iso`: The staging directory for GRUB and SquashFS.

*NOTE ON /tmp STORAGE:*
Because `/tmp` is cleared upon system reboot, ensure you back up your chroot 
directory or script modifications before shutting down your host system!

========================================================================
1. INSTALL HOST PREREQUISITES
========================================================================
Run the following command on your Linux Mint/Debian host to install all 
required build tools and GPG keyrings:

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

========================================================================
2. PREPARE CUSTOM BINARIES (OPTIONAL)
========================================================================
If you have custom compiled Vala/C binaries (such as mu-wm or tech-hud),
place them into a directory named 'custom-bin' in the project root:

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

If no 'custom-bin' folder exists, the build script will automatically 
fall back to IceWM as the default window manager.

========================================================================
3. FULL INITIAL BUILD
========================================================================
Make the main build script executable and run it with root privileges. 
This will download Debian stable packages, assemble the chroot, and build
the initial ISO (~470 MB):

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

========================================================================
4. FAILSAFE WORKFLOW: MODIFYING & REBUILDING WITHOUT REDOWNLOADING
========================================================================
To modify the OS without downloading all packages again:

STEP A: Enter the Chroot Environment
------------------------------------
Run `enter-chroot.sh` to open an interactive shell inside your live system.
Virtual pseudo-filesystems (/proc, /sys, /dev) will be safely mounted.

   sudo ./enter-chroot.sh

Inside the chroot, you can:
- Install packages: `apt update && apt install <package-name>`
- Edit user configs: Modify `/home/live/.xinitrc` or `/home/live/.config/`
- Add binaries directly: Copy files into `/usr/local/bin/`

Type `exit` when done. The script will automatically unmount pseudo-filesystems.

STEP B: Fast Rebuild of the ISO
-------------------------------
Re-generate the SquashFS compression and the GRUB bootable ISO in seconds:

   sudo ./rebuild-iso.sh

========================================================================
5. BACKUP YOUR CHROOT (PREVENT DATA LOSS)
========================================================================
Since `/tmp` is wiped on host reboot, create a local backup of your modified 
chroot directory if you plan to work on it across multiple sessions:

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

To restore a backup into `/tmp` after a host reboot:

   sudo mkdir -p /tmp/muppy10-build
   sudo cp -a ~/muppy10-build-backup/* /tmp/muppy10-build/

========================================================================
6. TEST THE RESULTING ISO IN QEMU
========================================================================
To quickly test your new ISO in a local QEMU virtual machine:

   sudo apt install -y qemu-system-x86
   qemu-system-x86_64 -m 2048 -enable-kvm -cdrom muppy10-amd64.iso

========================================================================
7. FREQUENTLY ASKED QUESTIONS (FAQ)
========================================================================

Q: If the system boots to RAM, will it save and where?
------------------------------------------------------------------------
By default, Muppy 10 runs as a pure live RAM system (volatile mode). Any 
changes made while running the live session are kept exclusively in RAM and 
are **lost upon reboot**. 
To enable persistence, you would need to configure `live-boot` persistence 
parameters in `grub.cfg` and create a dedicated persistence partition or 
loop file (`persistence`).

Q: Can or must the system be installed and how?
------------------------------------------------------------------------
The system **does not have to be installed**—it is designed to run completely 
standalone from USB/RAM. However, it *can* be installed to a local hard drive 
if desired. Because this is a minimal custom build, there is no heavy GUI 
installer pre-configured. Manual installation can be done from within the live 
environment by partitioning a target drive, copying the root filesystem via 
`rsync`, and installing GRUB (`grub-install`).

Q: How much smaller could we be without Xorg / Picom?
------------------------------------------------------------------------
Dropping `xserver-xorg-core`, video drivers, utilities, and `picom` would 
reduce the ISO and RAM footprint by roughly **30 to 50 MB**, and save a modest 
amount of RAM overhead. 
However, doing so means losing traditional X11 window management. You would 
have to render your UI (like your Tech-HUD or custom Vala applications) 
directly via Linux Framebuffer (`/dev/fb0`), DRM/KMS, or a lightweight Wayland 
compositor instead.