docs: work on new quickstart guide

www/docs/ctrl/bootstrapping.mdx

@@ -20,13 +20,13 @@ The bootstrapping process can include a variety of steps such as:
 - Generating unique device identifiers and security certificates.
 - Customizing configurations to suit device-specific requirements.
 
-When [configured to run before the init process](./state-management.md), Rugix Ctrl can also carry out bootstrapping steps. For instance, unless configured otherwise, it will grow the partition table and initialize the data partition where the persistent state lives. Rugix Ctrl's bootstrapping process is flexible and you can adapt it to your specific needs by adding bootstrapping hooks.
+When [configured to run before the init system](./state-management.md), Rugix Ctrl can also carry out bootstrapping steps. For instance, unless configured otherwise, it will grow the partition table and initialize the data partition where the persistent state lives. Rugix Ctrl's bootstrapping process is flexible and you can adapt it to your specific needs by adding bootstrapping hooks.
 
 :::info
 The bootstrapping process is configured in the `/etc/rugix/bootstrapping.toml` configuration file. It requires a config partition to be configured and present. The config partition must contain a file `/.rugpi/bootstrap` to trigger the bootstrapping process. This file is deleted after the bootstrapping process to ensure that it does not run again.[^bootstrap-in-production]
 :::
 
-[^bootstrap-in-production]: Note that a malicious actor may be able to create this file on a production device and then trigger the bootstrapping process, even if secure boot and other security measurements are in place. This may pose a security risk. In those cases, it is recommended to use a user-defined early bootstrapping step that will check whether the device should be bootstrapped using some other source, such as one-time-programmable memory, and abort the process based on the outcome of that check.
+[^bootstrap-in-production]: Note that a malicious actor may be able to create this file on a production device and then trigger the bootstrapping process, even if secure boot and other security measures are in place. This may pose a security risk. In those cases, it is recommended to use a user-defined `prepare` bootstrapping hook that will check whether the device should be bootstrapped using some other source, such as one-time-programmable memory, and abort the process based on the outcome of that check.
 
 
 ## System Layout
@@ -39,7 +39,7 @@ The layout always affects the disk of the booted root filesystem. Unless configu
 
 Rugix Ctrl supports MBR (DOS) partition tables and GPT partition tables. Here are two example layouts:
 
-```toml title="bootstrapping.toml"
+```toml title="/etc/rugix/bootstrapping.toml"
 [layout]
 type = "mbr"
 partitions = [
@@ -53,7 +53,7 @@ partitions = [
 ]
 ```
 
-```toml title="bootstrapping.toml"
+```toml title="/etc/rugix/bootstrapping.toml"
 [layout]
 type = "gpt"
 partitions = [
@@ -84,7 +84,7 @@ type = "none"
 ```
 
 :::note
-Rugix Ctrl will only create new partitions that do not already exist and grow partitions that already exist. Furthermore, it will only create filesystems on partitions that it created itself to prevent accidental data loss.
+Rugix Ctrl will only create new partitions that do not already exist and grow partitions that do already exist. Furthermore, it will only create filesystems on partitions that it created itself to prevent accidental data loss.
 :::
 
 
@@ -110,6 +110,10 @@ In addition, the config partition is mounted read-only (usually at `/run/rugix/m
 
 ## Configuration Reference
 
+For reference, here is the complete schema for the bootstrapping configuration file:
+
 <JSONSchemaViewer schema={ConfigSchema} viewerOptions={{
     DescriptionComponent: ({description}) => <ReactMarkdown children={description} />
-}}/>
+}}/>
+
+You will find the most recent version of this schema [on GitHub](https://github.com/silitics/rugix/blob/main/schemas/rugix-ctrl-bootstrapping.schema.json).

www/docs/ctrl/hooks.md

@@ -6,9 +6,9 @@ sidebar_position: 4
 
 _Hooks_ provide a powerful mechanism to inject custom behavior at various stages of Rugix Ctrl's operation.
 
-Hooks are scripts that are executed at specific points in the execution flow of an operation. For instance, you can run custom scripts after an update is installed (but before the system is rebooted) or before it is committed. Hooks are organized based on the type of the operation and the point in time, referred to as _stage_, when they should run. In addition, each hook has a _rank_. You can use hooks to customize and extend various parts of Rugix Ctrl based on your needs and requirements.
+Hooks are scripts that are executed at specific points in the execution of an operation. For instance, you can run custom scripts after an update is installed (but before the system is rebooted) or before it is committed. Hooks are organized based on the type of the operation and the point in time, referred to as _stage_, when they should run. In addition, each hook has a _rank_, specifying the order in which hooks run. You can use hooks to customize and extend various parts of Rugix Ctrl based on your needs and requirements.
 
-Hooks are placed in `/etc/rugix/hooks`. Each operation gets its own directory, for instance, `/etc/rugix/hooks/bootstrap` contains [bootstrapping hooks](./bootstrapping.md) and `/etc/rugix/hooks/system-commit` contains [system commit hooks](./over-the-air-updates.md). Each directory has a subdirectory for each stage of the respective operation. For instance, `system-commit` has a `prepare` stage. The hooks of this stage will run before performing the commit. To add a hook to the respective stage, a file with the name `<rank>-<name>` is placed in the stage directory. Importantly, hooks with a lower `<rank>` run earlier than those with a higher `<rank>`.
+Hooks are placed in `/etc/rugix/hooks`. Each operation gets its own directory, for instance, `/etc/rugix/hooks/bootstrap` contains [bootstrapping hooks](./bootstrapping.md) and `/etc/rugix/hooks/system-commit` contains [system commit hooks](./over-the-air-updates.md). Each directory gets a subdirectory for each stage of the respective operation. For instance, `system-commit` has a `prepare` stage. The hooks of this stage will run before performing the commit. To add a hook to the respective stage, a file with the name `<rank>-<name>` is placed in the stage directory. Here, `<rank>` is an integer and hooks with a lower rank run earlier than those with a higher rank.
 
 For instance, you may add the following file to add a check before committing to an update:
 

www/docs/ctrl/index.md

@@ -4,15 +4,15 @@ _Rugix Ctrl_ is a powerful tool for robust over-the-air system updates and syste
 
 To set the stage, let's first focus on the things that could go wrong and the ideal features and properties of an update solution.
 
-1. **Interrupted Updates:** If something interrupts the update process, such as an unplanned power outage, a partially installed update may leave the system in an inoperable state. Therefore, a robust update solution must be _transactional_, ensuring that updates are either installed completely or not at all, always leaving the system in an operational state, no matter what happens.
+1. **Interrupted Updates:** If something interrupts the update process, such as an unplanned power outage, a partially installed update may leave the system in an inoperable state. Therefore, a robust update solution must be _atomic_, ensuring that updates are either installed completely or not at all, always leaving the system in an operational state, no matter what happens.
 
 2. **Uncertain Production Environment:** While extensive testing should be done prior to deploying any updates, replicating the exact production environment and conditions can be difficult. An update that turns out to be incompatible with the particularities of the production environment under difficult to replicate conditions may leave the system in an inoperable state. Therefore, a robust update solution must have the possibility for _on-device validation and rollback_ of updates. If any problems are detected with an update on a particular device, a rollback to the previous, known-good version should be automatically triggered.
 
 3. **Data Loss and Accidental State:** Whenever an update is installed, the existing state of a system must be handled carefully to ensure that no data is lost. For instance, user settings and data stored on the device must be preserved. At the same time, a system must be safeguarded against corruption by _accidental state_ that should not be kept, such as configuration files incompatible with the new version. Therefore, a robust update solution must provide reliable _state management_ mechanisms.
 
 4. **Cyber Attacks:** A malicious actor may try to compromise a device by installing a manipulated update. Therefore, an update solution should provide mechanisms to prevent manipulated updates from being installed.
 
-Rugix Ctrl addresses these challenges by ensuring transactional updates, on-device validation with rollback capabilities, reliable state management, and protection against malicious updates. By utilizing Rugix Ctrl, you can rest assured that your devices remain reliable, secure, and up-to-date, **allowing you to focus on delivering value to your users**.
+Rugix Ctrl addresses these challenges by ensuring atomic updates, on-device validation with rollback capabilities, reliable state management, and protection against malicious updates. By utilizing Rugix Ctrl, you can rest assured that your devices remain reliable, secure, and up-to-date, **allowing you to focus on delivering value to your users**.
 
 
 ## High-Level Overview

www/docs/ctrl/over-the-air-updates.mdx

@@ -10,18 +10,24 @@ import ConfigSchema from "@site/schemas/rugix-ctrl-system.schema.json";
 
 # Over-the-Air Updates
 
-Rugpi supports robust *over-the-air* (OTA) updates with rollback support to the previous version.
-OTA updates comprise the full system including firmware files and the boot configuration.
-Rugpi uses an A/B approach ensuring that a working copy of the previous version is always kept.
-This approach drastically reduces the likelihood of bricking devices in the field due to corrupted software caused by a failed or incomplete update, thereby reducing any related support effort.
-In addition, it has the following advantages:
+Rugix Ctrl's core functionality is the safe installation of _over-the-air_ (OTA) system updates.
+
+**A/B Update Scheme.** A typical Rugix Ctrl setup uses an _A/B update scheme_ with redundant system partitions (A and B). When an update is available, it is installed on the inactive partition (e.g., if the device is currently using partition A, the update is installed on partition B). This allows the device to temporarily switch to the updated partition upon reboot, ensuring a seamless and fail-safe update process as the previous partition remains untouched and can be reverted to in case of any issues. After on-device validation of the update, the update is then committed by permanently switching to the now active partition as the default boot partition. This approach drastically reduces the likelihood of bricking devices in the field due to corrupted or incompatible software and failed or incomplete updates, thereby minimizing any related support effort. In addition, it has the following advantages:
 
 - OTA updates can almost completely run in the background, without adversely affecting any users of a device.
 The only service interruption is caused, when the device reboots into the new version.
 Rebooting to finalize an update can happen at the discretion of users and, if all goes well, does not take longer than any normal reboot, minimizing any inconveniences.
-- As the previous version is kept, a rollback to the old version is possible if users experience any problems with the new version.[^1]
+- As the previous version is kept, a rollback to the old version is possible if users experience any problems with the new version.[^rollback]
+
+[^rollback]: This requires application support.
+
+**Other Update Schemes.** We generally recommend using an A/B update scheme due to the advantages stated above. For cases where an A/B update scheme is not the right choice, Rugix Ctrl can flexibly be configured for other update schemes, for instance, an asymmetric setup with a recovery partition or a setup with more than two redundant system partitions.
+
+To commit and switch between systems, Rugix Ctrl needs to integrate with the bootloader of the system.
 
-[^1]: This requires application support.
+:::tip
+When building a system with Rugix Bakery for one of the generic and specific targets, you will get a system with a working OTA update integration out-of-the-box using an A/B update scheme. In that case, no configuration is necessary.
+:::
 
 
 ### A/B Update Scheme