chore(docs): reorganize setup guides

Author: azenla

README.md

@@ -18,6 +18,9 @@ existing UEFI bootloader or booted by the hardware directly.
 
 Sprout is licensed under Apache 2.0 and is open to modifications and contributions.
 
+**NOTE**: Sprout is still in beta. Some features may not work as expected.
+Please [report any bugs you find](https://github.com/edera-dev/sprout/issues/new/choose).
+
 ## Background
 
 At [Edera] we make compute isolation technology for a wide variety of environments, often ones we do not fully control.
@@ -37,11 +40,21 @@ simplify installation and usage.
 
 ## Documentation
 
-- [Ubuntu Secure Boot Setup Guide]
-- [Fedora Setup Guide]
-- [Generic Linux Setup Guide]
-- [Alpine Edge Setup Guide]
-- [Windows Setup Guide]
+### Setup Guides
+
+Some guides support Secure Boot and some do not.
+We recommend running Sprout without Secure Boot for development, and with Secure Boot for production.
+
+| Operating System | Secure Boot Enabled | Link                                                  |
+|------------------|---------------------|-------------------------------------------------------|
+| Ubuntu           | ✅                   | [Setup Guide](./docs/setup/signed/ubuntu.md)          |
+| Fedora           | ❌                   | [Setup Guide](./docs/setup/unsigned/fedora.md)        |
+| Alpine Edge      | ❌                   | [Setup Guide](./docs/setup/unsigned/alpine-edge.md)   |
+| Generic Linux    | ❌                   | [Setup Guide](./docs/setup/unsigned/generic-linux.md) |
+| Windows          | ❌                   | [Setup Guide](./docs/setup/unsigned/windows.md)       |
+
+### Project Documentation
+
 - [Development Guide]
 - [Contributing Guide]
 - [Sprout License]
@@ -50,8 +63,6 @@ simplify installation and usage.
 
 ## Features
 
-**NOTE**: Sprout is still in beta.
-
 ### Current
 
 - [x] Loadable driver support
@@ -148,11 +159,6 @@ autoconfigure = true
 ```
 
 [Edera]: https://edera.dev
-[Ubuntu Secure Boot Setup Guide]: ./docs/ubuntu-secure-boot-setup.md
-[Fedora Setup Guide]: ./docs/fedora-setup.md
-[Generic Linux Setup Guide]: ./docs/generic-linux-setup.md
-[Alpine Edge Setup Guide]: ./docs/alpine-edge-setup.md
-[Windows Setup Guide]: ./docs/windows-setup.md
 [Development Guide]: ./DEVELOPMENT.md
 [Contributing Guide]: ./CONTRIBUTING.md
 [Sprout License]: ./LICENSE

docs/ubuntu-secure-boot-setup.md docs/setup/signed/ubuntu.mddocs/ubuntu-secure-boot-setup.md renamed to docs/setup/signed/ubuntu.md

@@ -1,6 +1,12 @@
-# Ubuntu Secure Boot Setup
+# Setup Sprout for Ubuntu with Secure Boot
 
-## Generate and Install Secure Boot Key
+## Prerequisites
+
+- Modern Ubuntu release: tested on Ubuntu 25.10 on ARM64
+- EFI System Partition mounted on `/boot/efi` (the default)
+- ext4 or FAT32/exFAT formatted `/boot` partition
+
+## Step 1: Generate and Install Secure Boot Key
 
 ```bash
 # Create a directory to store the Secure Boot MOK key and certificates.
@@ -28,7 +34,7 @@ $ mokutil --import mok.cer
 # Select "Reboot" to boot back into your Operating System.
 ```
 
-## Prepare Secure Boot Environment
+## Step 2: Prepare the Secure Boot Environment
 
 ```bash
 # Create a directory for Sprout EFI artifacts.
@@ -45,13 +51,13 @@ $ cp /usr/lib/shim/mmaa64.efi /boot/efi/EFI/sprout/mmaa64.efi
 $ cp /usr/lib/shim/fbaa64.efi /boot/efi/EFI/sprout/fbaa64.efi
 ```
 
-## Install Unsigned Sprout
+## Step 3: Install Unsigned Sprout
 
 Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
 For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM64 systems, download the `sprout-aarch64.efi` file.
 Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.efi` on your EFI System Partition.
 
-## Sign Sprout for Secure Boot
+## Step 4: Sign Sprout for Secure Boot
 
 ```bash
 # For x86_64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call.
@@ -69,7 +75,14 @@ $ sbsign \
     /boot/efi/EFI/sprout/sprout.unsigned.efi
 ```
 
-## Sign EFI Drivers
+## Step 5: Install and Sign EFI Drivers
+
+You will need a filesystem EFI driver if `/boot` is not FAT32 or ExFAT.
+If `/boot` is FAT32 or ExFAT, you can skip this step.
+
+Most Ubuntu systems use an ext4 filesystem for `/boot`.
+You can download an EFI filesystem driver from [EfiFs releases](https://github.com/pbatard/EfiFs/releases).
+For ext4, download the `ext2` file for your platform. It will work for ext4 filesystems too.
 
 If you have an EFI driver, copy the driver to `/boot/efi/EFI/sprout/DRIVER_NAME.unsigned.efi` for signing.
 
@@ -86,7 +99,7 @@ $ sbsign \
     /boot/efi/EFI/sprout/ext4.unsigned.efi
 ```
 
-## Create Sprout Configuration
+## Step 6: Create Sprout Configuration
 
 Write the following to the file `/boot/efi/sprout.toml`:
 
@@ -100,6 +113,8 @@ version = 1
 linux-options = "root=UUID=MY_ROOT_UUID"
 
 # load an ext4 EFI driver.
+# skip this if you do not have an filesystem driver.
+# if your filesystem driver is not named ext4, change accordingly.
 [drivers.ext4]
 path = "\\EFI\\sprout\\ext4.efi"
 
@@ -113,14 +128,17 @@ autoconfigure = true
 Ensure you add the signed driver paths to the configuration, not the unsigned ones.
 If you do not have any drivers, exclude the drivers section entirely.
 
-## Configure Sprout Boot Entry
+## Step 7: Configure Sprout Boot Entry
 
-```bash
-# In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
+In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
 
+```bash
 # For x86_64, run this command to add Sprout as the default boot entry.
 $ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
 
 # For aarch64, run this command to add Sprout as the default boot entry.
 $ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
 ```
+
+Reboot your machine and it should boot into Sprout.
+If Sprout fails to boot, it should boot into the original bootloader.

docs/alpine-edge-setup.md docs/setup/unsigned/alpine-edge.mddocs/alpine-edge-setup.md renamed to docs/setup/unsigned/alpine-edge.md

@@ -1,4 +1,4 @@
-# Setup Sprout on Alpine Edge
+# Setup Sprout for Alpine Edge without Secure Boot
 
 ## Prerequisites
 

docs/fedora-setup.md docs/setup/unsigned/fedora.mddocs/fedora-setup.md renamed to docs/setup/unsigned/fedora.md

@@ -1,4 +1,4 @@
-# Setup Sprout on Fedora
+# Setup Sprout for Fedora without Secure Boot
 
 ## Prerequisites
 

docs/generic-linux-setup.md docs/setup/unsigned/generic-linux.mddocs/generic-linux-setup.md renamed to docs/setup/unsigned/generic-linux.md

@@ -1,4 +1,4 @@
-# Setup Sprout to boot Linux
+# Setup Sprout for Linux without Secure Boot
 
 ## Prerequisites
 

docs/windows-setup.md docs/setup/unsigned/windows.mddocs/windows-setup.md renamed to docs/setup/unsigned/windows.md

@@ -1,4 +1,4 @@
-# Setup Sprout to boot Windows
+# Setup Sprout for Windows without Secure Boot
 
 ## Prerequisites