docs: work on the next version

www/docs/bakery/advanced/_category_.json

@@ -1,6 +1,6 @@
 {
     "label": "Advanced Topics",
-    "position": 100,
+    "position": 10,
     "link": {
         "type": "doc",
         "id": "index"

www/docs/bakery/advanced/caching.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 1
 ---
 
 # Caching

www/docs/bakery/advanced/index.md

@@ -1 +1,3 @@
-# Advanced Topics
+# Advanced Topics
+
+This part of the documentation covers more advanced topics related to Rugix Bakery.

www/docs/bakery/images.md

@@ -4,61 +4,37 @@ sidebar_position: 5
 
 # Images
 
-The configuration file `rugpi-bakery.toml` contains a declaration for each image that can be built.
-
-An *image declaration* has the following structure:
-
-```typescript
-type Image = {
-    layer: string;
-    architecture: "amd64" | "arm64" | "armv7" | "armhf" | "arm";
-    target: "generic-grub-efi" | "rpi-tryboot" | "rpi-uboot";
-    size?: string;
-    layout?: ImageLayout;
-}
-```
-
-Each image configuration has a mandatory `layer` property specifying the name of the layer containing the filesystems for the image, in particular, the root filesystem.
-For further details on layers, checkout the [user guide's section on System Customization](./system-customization.md).
-In addition, the configuration must specify an architecture and a target and may specify a size and an image layout.
+As part of the project configuration you can define _system images_. A system image is a binary blob containing a partition table together with the required partitions and filesystems to boot a fully-functioning system. Images are typically used to provision new systems by flashing them onto a system's storage, e.g., integrated eMMC flash memory or an SSD.
 
-## Architectures
+Images are defined in the `images` section of the project configuration. Here is an example taken from the [Debian template](https://github.com/silitics/rugpi/tree/main/bakery/templates/debian-grub-efi):
 
-Rugpi supports the following CPU architectures.
-
-| Architecture | Description | Alpine | Debian | Raspberry Pi OS |
-| ------------ | ----------- | ------ | ------ | --------------- |
-| `amd64` | 64-bit x86 | `x86_64` | `amd64` | – |
-| `arm64` | 64-bit ARMv8 | `aarch64` | `arm64` | `arm64` |
-| `armv7` | 32-bit ARMv7 | `armv7` | `armhf` | – |
-| `armhf` | 32-bit ARMv6 (Hard-Float) | `armhf` | – | `armhf` |
-| `arm` | 32Tbit ARMv6 | – | `armel` | – |
+```toml
+[images.customized-arm64]
+layer = "customized"
+architecture = "arm64"
+target = "generic-grub-efi"
+```
 
-Note that different distributions have different and sometimes inconsistent names for different CPU families.
-For instance, what Debian calls `armhf` is called `armv7` for Alpine Linux and not the same as `armhf` for Raspberry Pi OS.
+This will instruct Rugix Bakery to build an image named `customized-arm64` based on the `customized` layer for `arm64` and using `generic-grub-efi` as a _device target_ (the image will work on any EFI-compatible hardware). 
 
-When building images the architecture reported by `uname -m` may not match the actual CPU and architecture of the device the image is intended for.
-For instance, when building an `armhf` image based on Rasbperry Pi OS, the architecture reported by `uname -m` during the build process is `armv7l`, however, when running the image later on a non-ARMv7 board (e.g., Pi Zero or Pi 1), then the architecture will be `armv6l`.
-We recommend always using the Rugpi architecture instead of `uname -m`.
+Every image is based on a layer providing, among other things, the root filesystem for the image. In addition, an [architecture](./#architectures) must be specified. The `target` setting is optional and used to select some defaults for supported devices.
 
 
 ## Targets
 
-When building a system image with Rugpi, you need to specify a *target* that is appropriate for your device.
-Targets typically support a whole family of devices and are categorized into *generic*, *specific*, and *unknown* targets.
+When building a system image with Rugix Bakery, you can specify a *target* that is appropriate for your device. Targets typically support a whole family of devices and are categorized into *generic*, *specific*, and *unknown* targets.
 
 - **Generic targets** are based on some standardized booting mechanism, such as [UEFI](https://en.wikipedia.org/wiki/UEFI) or [EBBR](https://github.com/ARM-software/ebbr).
 Generic targets are suitable for any device that supports the respective booting mechanism.
 - **Specific targets**, on the other hand, are limited to a certain family of devices.
 They come with all necessary device-specific configurations resulting in a bootable image that works out-of-the-box.
-- **Unknown targets** are for devices that do not conform to a standardized booting mechanism and are not specifically supported by Rugpi.
-Using unknown targets allows building images for unsupported devices; however, these images usually require additional device-specific modifications to become bootable.
+- **Unknown targets** are for devices that do not conform to a standardized booting mechanism and are not specifically supported by Rugix Bakery. Using unknown targets allows building images for unsupported devices; however, these images may require additional device-specific modifications to become bootable.
 
 The target for an image is set by the `target` property in the image declaration.
 
 For supported devices and the required targets, checkout the documentation on [Supported Devices](/devices).
 
-Currently, Rugpi supports the following targets:
+Currently, Rugix Bakery supports the following targets:
 
 - `generic-grub-efi`: A generic target that uses Grub as the bootloader and produces an image bootable on any EFI-compatible system.
 This is the right target for commodity AMD64 and ARM64 hardware or VMs.
@@ -77,28 +53,25 @@ To this end, the following recipes can be used:
 - `core/rpi-alpine-setup`: For Alpine with `rpi-tryboot`.
 - `core/rpi-raspios-setup`: For Raspberry Pi OS with `rpi-tryboot` or `rpi-uboot`.
 
-## Image Layout (Experimental)
-
-You can also specify an image layout.
+## Layouts (Experimental)
 
 :::warning
-
-**This is an experimental feature. We may make breaking changes in minor versions.**
-
+**This is an experimental feature. We may introduce breaking changes in minor versions.**
 :::
 
-Usually, you do not need to worry about image layouts as Rugpi automatically selects a suitable layout based on the target.
-For advanced use cases or to adapt Rugpi to a device that is not officially supported, Rugpi also gives you the flexibility to configure how exactly the image should be built.
-Currently, this is limited to creating partitions with an optional filesystem based on some root directory.
+Usually, you do not need to worry about image layouts as Rugix Bakery automatically selects a suitable layout based on the device target.
+For advanced use cases or devices that are not officially supported, Rugix Bakery also gives you the flexibility to configure how exactly the image should be built.
+Currently, this is limited to creating partitions with optional filesystems.
 
 #### Image Creation Process
 
 The process of creating an image roughly works as follows:
 
-1. Compute a partition table based on the specified image layout.
-2. Create an image and partition it according to the computed table.
-3. Patch the boot configuration based on the target.
-4. Create the filesystems based on the specified root directories.
+1. Create the required filesystems from the layer.
+2. Compute a partition table based on the specified image layout and filesystems.
+3. Create an image and partition it according to the computed table.
+4. Copy the prepared filesystems into the image.
+5. Patch the boot configuration based on the target.
 
 Supported partition tables:
 - `gpt`: [GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table) (modern partition table, part of the UEFI standard)
@@ -108,18 +81,4 @@ Supported filesystems:
 - `ext4`: [Ext4 Filesystem](https://en.wikipedia.org/wiki/Ext4)
 - `fat32`: [FAT32 Filesystem](https://en.wikipedia.org/wiki/File_Allocation_Table)
 
-The image layout is specified within the `layout` section of the image configuration has the following structure:
-
-```typescript
-type Layout = {
-    type: "gpt" | "mbr";
-    partitions: Partition[];
-}
-
-type Partition = {
-    type?: string;
-    size?: string;
-    filesystem?: "ext4" | "fat32";
-    root?: string;
-}
-```
+The image layout is specified in the `layout` section. For details, we refer to the [project configuration reference](./projects.mdx#project-configuration).

www/docs/bakery/index.md

@@ -36,6 +36,22 @@ Rugix Bakery currently requires the container to run in privileged mode such tha
 
 [^privileges]: Existing tools use different approaches to set up an environment that looks like the final system without requiring privileges. For instance, Yocto uses a tool called [Pseudo](https://git.yoctoproject.org/pseudo/about/) (an alternative to the better-known tool [Fakeroot](https://manpages.debian.org/bookworm/pseudo/fakeroot.1.en.html)), to intercepts calls to system APIs via `LD_PRELOAD` and thereby fake a root environment. This approach has limitations, for instance, it does not work with statically-linked binaries and also does not allow starting services binding sockets to ports below 1024. Rugix Bakery strives to provide a container-like environment by using Linux namespaces and process isolation which does not suffer from the same limitations as existing approaches and thereby mimics a real system more closely.
 
+## Architectures
+
+Rugix Bakery supports the following CPU architectures:[^architecture-plans]
+
+[^architecture-plans]: We plan to support more architectures in the future. Feel free to [open an issue on GitHub](https://github.com/silitics/rugpi/issues/new).
+
+| Architecture | Description | Alpine | Debian | Raspberry Pi OS |
+| ------------ | ----------- | ------ | ------ | --------------- |
+| `amd64` | 64-bit x86 | `x86_64` | `amd64` | – |
+| `arm64` | 64-bit ARMv8 | `aarch64` | `arm64` | `arm64` |
+| `armv7` | 32-bit ARMv7 | `armv7` | `armhf` | – |
+| `armhf` | 32-bit ARMv6 (Hard-Float) | `armhf` | – | `armhf` |
+| `arm` | 32Tbit ARMv6 | – | `armel` | – |
+
+Note that different distributions have different and sometimes inconsistent names for different CPU families.
+For instance, what Debian calls `armhf` is called `armv7` for Alpine Linux and not the same as `armhf` for Raspberry Pi OS.
 
 ## Build Process: High-Level Introduction
 

www/docs/bakery/recipes.mdx

@@ -109,6 +109,10 @@ Rugix Bakery will set up a semi-isolated environment (similar to a container) th
 You can use `install` steps to customize a system in the same way you normally would when you set up a system and perform customizations manually via a local shell. For instance, you can install packages or enable certain system services. Note that services will not run when executing a `run` step, you can, however, [start them as part of the step](./advanced/services.md).
 :::
 
+Note that the architecture reported by `uname -m` during an `install` step may not match the actual CPU and architecture of the device the system is intended for.
+For instance, when building an `armhf` system based on Rasbperry Pi OS, the architecture reported by `uname -m` during the build process is `armv7l`, however, when running the system later on a non-ARMv7 board (e.g., Pi Zero or Pi 1), then the architecture will be `armv6l`.
+We recommend always using the Rugix architecture instead of `uname -m`.
+
 ### Environment Variables
 
 Rugix Bakery will expose the following environment variables when running steps: