diagrams and simulation

docs/00-series-overview.md

@@ -71,7 +71,7 @@ The emphasis is always on understanding the underlying design rather than memori
 
 ## Repository Structure
 
-The structure below shows the planned repository. The `diagrams/` and `examples/` directories will be added as the practical material develops.
+The structure below includes the current documentation, PlantUML diagrams, and A/B simulation. Hardware demonstrations and later chapters will be added as the practical material develops.
 
 ```text
 ota-reference-design/
@@ -86,12 +86,12 @@ ota-reference-design/
 │   ├── ...
 │
 ├── diagrams/
-│   └── plantuml/
+│   ├── plantuml/
+│   └── rendered/
 │
 ├── examples/
-│   ├── raspberry-pi/
-│   ├── qemu/
 │   └── simulations/
+│       └── ab-trial-boot/
 │
 ├── adr/
 │   ├── ADR-001-repository-name.md
@@ -196,6 +196,8 @@ Where possible, theoretical discussions are accompanied by practical material, i
 
 The objective is to connect high-level architecture with practical implementation.
 
+Available now: [PlantUML diagrams and SVG previews](../diagrams/readme.md) and a [Python A/B trial boot simulation](../examples/simulations/ab-trial-boot/readme.md). Raspberry Pi and QEMU demonstrations are planned.
+
 ---
 
 ## Intended Audience

docs/03-system-architecture.md

@@ -45,6 +45,12 @@ Alongside the update files, it needs a few details: which version this is, which
 
 These are roles, not a shopping list of separate services. One tool may cover several of them. What matters is knowing who handles each step.
 
+The following view shows the roles and the server/device boundary for the system-update example used in the next chapter.
+
+![OTA roles and device boundary](../diagrams/rendered/ota-architecture.svg)
+
+[PlantUML source](../diagrams/plantuml/ota-architecture.puml)
+
 ## 3. One Update, Start to Finish
 
 Imagine a device running version 1. Version 2 is ready. In this example, the device can prepare the new system while keeping the previous one available for recovery.

docs/04-starting-an-updated-system-or-service.md

@@ -99,6 +99,12 @@ Returning to a previous version is called **rollback**. Keeping A available make
 
 [ADR-014: Trial Boot and Confirmation for System Updates](../adr/ADR-014-trial-boot-and-confirmation.md) explains when to choose this policy and what the platform must support.
 
+The state diagram separates an explicit health-check failure from a startup failure that prevents the checks from running. It also shows the checks after returning to A.
+
+![A/B trial boot and recovery](../diagrams/rendered/ab-trial-boot.svg)
+
+[PlantUML source](../diagrams/plantuml/ab-trial-boot.puml) · [Runnable simulation and failure scenarios](../examples/simulations/ab-trial-boot/readme.md)
+
 ## 5. Example: Starting an Updated Service
 
 Now imagine a device with a stable system platform and an independently updated communication service. Version 1 works. Version 2 arrives as a package.

docs/05-storage-layout.md

@@ -64,6 +64,12 @@ The layout still has shared parts. If an update damages the shared boot componen
 
 Two slots on one storage device also do not protect against failure of that whole device.
 
+The following diagram adds access responsibilities to the logical layout. A is running while the installer prepares B. Trial requests and confirmation use the platform's boot control interface.
+
+![A/B storage areas and access responsibilities](../diagrams/rendered/ab-storage-layout.svg)
+
+[PlantUML source](../diagrams/plantuml/ab-storage-layout.puml) · [Simulation of saved boot state across resets](../examples/simulations/ab-trial-boot/readme.md)
+
 ## 3. What Lives Outside the System Slots?
 
 A system release provides common software. Device identity and calibration belong to an individual device. Installing a system image must not replace them with values from the release build.