dsoxlab 0.2.2__tar.gz → 0.2.4__tar.gz

{dsoxlab-0.2.2 → dsoxlab-0.2.4}/.github/workflows/appliance.yml

@@ -9,16 +9,23 @@
 #   2. un build d'image de vingt minutes ne doit ni retarder une publication PyPI,
 #      ni pouvoir la faire échouer.
 #
-# Sur les tags, il ne se déclenche que sur les **mineurs** (`v0.3.0`, `v0.4.0`) :
-# l'image n'épingle pas la version de dsoxlab, elle installe la dernière au
-# premier démarrage, donc republier un gigaoctet à chaque correctif coûterait
-# cher pour ne rien changer.
+# Il se déclenche sur **toute** version publiée, correctifs compris. La règle
+# précédente — les seuls tags mineurs — économisait de la bande passante et
+# coûtait plus cher que ça : elle laissait la doc annoncer une appliance que la
+# dernière release ne portait pas, et obligeait le lecteur à chercher laquelle
+# des releases précédentes en avait une. « La dernière release porte l'image »
+# est la seule phrase qu'on n'a pas à nuancer.
+#
+# Ce que ça ne coûte pas : de l'espace qui s'accumule. Seuls les deux derniers
+# jeux d'images sont conservés (voir l'étape de rétention), et l'image
+# n'épinglant aucune version de dsoxlab, une ancienne n'offre rien d'autre que
+# son poids.
 
 name: Appliance
 
 on:
   push:
-    tags: ["v[0-9]+.[0-9]+.0"]
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
   workflow_dispatch:
     inputs:
       tag:
@@ -97,6 +104,24 @@ jobs:
           echo "sum=$sum" >> "$GITHUB_OUTPUT"
           echo "ISO : $name"
 
+      - name: Prepare the build directory on /mnt
+        # `/mnt` has the space (~70 GB against ~14 on `/`), but it belongs to
+        # root: the runner cannot create anything there. The first real run of
+        # this workflow died on exactly that, four hundredths of a second in —
+        # a defect no local build could show, since the directory exists and is
+        # writable on a developer's machine.
+        #
+        # `out/` is deliberately NOT created: Packer refuses to start when its
+        # output directory already exists ("It must not exist"), which is how
+        # it guarantees it never writes over a previous build. Creating it here
+        # traded one failure for another, one step later — measured on the
+        # second real run.
+        run: |
+          set -euo pipefail
+          sudo mkdir -p "${BUILD_DIR}/tmp"
+          sudo chown -R "$(id -u):$(id -g)" "${BUILD_DIR}"
+          df -h "${BUILD_DIR}"
+
       - name: packer init && validate
         working-directory: packer
         env:
@@ -104,7 +129,6 @@ jobs:
           ISO_SUM: ${{ steps.iso.outputs.sum }}
         run: |
           set -euo pipefail
-          mkdir -p "${BUILD_DIR}/out" "${BUILD_DIR}/tmp"
           packer init .
           packer validate \
             -var "image_version=${GITHUB_REF_NAME#v}" \
@@ -206,6 +230,24 @@ jobs:
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
+
+          # Les deux workflows partent du même tag : celui-ci construit pendant
+          # vingt minutes, `release.yml` publie en deux. La Release existe donc
+          # en pratique bien avant qu'on arrive ici — mais « en pratique » n'est
+          # pas une garantie, et un upload sur une Release absente échouerait
+          # sur un message qui ne dirait pas pourquoi. On attend, et on le dit.
+          restants=30                      # 30 × 20 s = dix minutes
+          until gh release view "$TAG" --repo "$REPO" >/dev/null 2>&1; do
+            restants=$((restants - 1))
+            if [ "$restants" -le 0 ]; then
+              echo "::error::La Release $TAG n'existe toujours pas après dix minutes."
+              echo "::error::Regardez release.yml : s'il a échoué, les images n'ont rien où s'attacher."
+              exit 1
+            fi
+            echo "En attente de la Release $TAG…"
+            sleep 20
+          done
+
           gh release upload "$TAG" --repo "$REPO" --clobber \
             "${BUILD_DIR}"/out/*.ova \
             "${BUILD_DIR}"/out/*.qcow2 \

{dsoxlab-0.2.2 → dsoxlab-0.2.4}/CHANGELOG.fr.md

@@ -9,6 +9,90 @@ et le projet suit le [versionnage sémantique](https://semver.org/lang/fr/).
 
 ## [Non publié]
 
+## [0.2.4] - 2026-09-26
+
+### Corrigé
+
+- **Le build de l'appliance a avancé d'une étape, et s'est arrêté sur la
+  précédente.** `/mnt` étant enfin accessible en écriture, c'est Packer qui a
+  refusé de démarrer : *Output directory '/mnt/appliance/out' already exists.
+  It must not exist.* Ce refus est une qualité — c'est ainsi que Packer
+  garantit qu'il n'écrase jamais un build précédent — et l'étape de
+  préparation créait précisément ce répertoire. Elle ne crée plus que le
+  parent et le répertoire temporaire, et laisse `out/` à Packer. Deux échecs
+  de suite au même endroit disent quelque chose qu'il vaut la peine de
+  retenir : un workflow qui n'a jamais tourné est un workflow qui ne marche
+  pas, et le seul moyen de le savoir est de le jouer.
+
+## [0.2.3] - 2026-09-26
+
+### Corrigé
+
+- **Le workflow de l'appliance n'avait jamais tourné, et il est mort au bout de
+  quatre centièmes de seconde.** `mkdir: cannot create directory
+  '/mnt/appliance': Permission denied` — sur un runner GitHub, `/mnt`
+  appartient à root, et c'est là qu'est la place (environ 70 Go contre 14 sur
+  `/`). Aucun build local ne pouvait le montrer : sur une machine de
+  développement, ce répertoire existe et s'écrit. Une étape dédiée le crée
+  désormais en `sudo` et le remet au runner.
+
+- **L'image est publiée à chaque release, et plus seulement aux mineures.**
+  L'ancienne règle économisait de la bande passante et coûtait plus qu'elle
+  n'économisait : la documentation annonçait une appliance que la dernière
+  release ne portait pas, et le lecteur devait deviner laquelle des
+  précédentes l'avait. « La dernière release porte l'image » est la seule
+  phrase qui n'appelle aucune nuance, et rien ne s'accumule puisque l'étape de
+  rétention garde les deux derniers jeux. Les deux workflows partant désormais
+  du même tag, l'upload attend que la Release existe au lieu de le supposer —
+  et dit quel workflow regarder si elle n'arrive jamais.
+
+### Modifié
+
+- **La documentation est un parcours, plus une pile de pages.** Relue de bout
+  en bout contre le code, elle portait des ruptures qu'aucune page seule ne
+  pouvait révéler :
+
+  `learner.fr.md` promettait `run` juste après le clonage d'un catalogue, alors
+  que **66 des 86 labs du catalogue Linux** sont des labs `vm` : ce `run` sort
+  en 2, le `provision` qu'il suggère sort en 1 faute de clé SSH, et ni
+  `instructor bootstrap`, ni `start`, ni le mot Terraform n'apparaissaient sur
+  la page. Elle nomme maintenant ce qu'un lab `vm` demande à une machine, et
+  met `start` en premier — la commande qui joue tout l'ordre en annonçant
+  chaque étape avec la commande qui la rejoue seule.
+
+  `catalog-author.fr.md` listait les fichiers d'un lab sans dire ce qu'on y
+  met. Le barème que `validate-structure` impose (`### … (20 pts)` face à un
+  en-tête `N tâches, M points`, et un point par test), le format de
+  `hints.yaml`, et l'emplacement de `conftest.py` — pytest s'exécute depuis la
+  racine du catalogue — n'étaient documentés nulle part.
+
+  Le README n'atteignait ni l'index, ni `exit-codes.fr.md`,
+  `machine-output.fr.md` et `infra-only.fr.md` : trois pages de référence
+  inaccessibles depuis la porte d'entrée.
+
+  La clé SSH était décrite comme quelque chose que le catalogue livre. Il ne la
+  livre pas : les catalogues publiés ignorent tout le répertoire `ssh/`, et
+  `provision` refuse de démarrer sans la moitié privée. Elle se génère **par
+  clone**, avec `instructor bootstrap`, apprenants compris.
+
+  `contract-v1.fr.md` se contredisait à neuf lignes d'intervalle sur le
+  caractère obligatoire de `repo.category`.
+
+- **`docs/appliance.fr.md` est un pas-à-pas**, de l'installation de VirtualBox
+  au premier lab, avec la vérification d'empreinte, la mémoire à donner à la
+  machine selon celle de l'hôte, ce que montre le premier démarrage en trois
+  temps, et un tableau de dépannage. Les deux README ouvrent sur les deux
+  façons d'entrer, chacune avec son parcours en quatre étapes.
+
+### Ajouté
+
+- **Rendre à César** : l'appliance est l'idée de [@cedric-ribier], et elle
+  existe parce qu'il en avait déjà construit une de bout en bout, documentée
+  dans [#91](https://github.com/stephrobert/dsoxlab/issues/91). Celle qui est
+  livrée ici s'en inspire directement.
+
+[@cedric-ribier]: https://github.com/cedric-ribier
+
 ## [0.2.2] - 2026-09-26
 
 ### Ajouté
@@ -28,9 +112,10 @@ et le projet suit le [versionnage sémantique](https://semver.org/lang/fr/).
 
   L'image **n'épingle rien**. Le premier démarrage installe le dernier dsoxlab, et
   les hyperviseurs seulement si l'hôte expose la virtualisation imbriquée, vérifiée
-  en direct et jamais supposée. D'où sa reconstruction sur les **tags mineurs
-  seulement** : republier un demi-gigaoctet à chaque correctif coûterait cher pour
-  ne rien changer.
+  en direct et jamais supposée. Elle est reconstruite à **chaque version
+  publiée**, correctifs compris : la dernière release porte l'image, et c'est la
+  seule phrase qui n'appelle aucune nuance. Rien ne s'accumule pour autant —
+  seuls les deux derniers jeux sont conservés.
 
   Mesuré, non estimé : **461 Mio** pour le qcow2 et **446 Mio** pour l'OVA,
   construits en 4 min 50 s, contre un budget que le workflow impose à 800 Mio. Une
@@ -41,7 +126,7 @@ et le projet suit le [versionnage sémantique](https://semver.org/lang/fr/).
   bonne sous Linux, plutôt que de les vendre à égalité.
 
 - **Seuls les deux derniers jeux d'images sont conservés sur les Releases.**
-  Environ 900 Mo par version mineure, pour toujours, pour des images qui
+  Environ 900 Mo par version, pour toujours, pour des images qui
   n'épinglent aucune version de dsoxlab et installent la dernière au premier
   démarrage : une ancienne n'offre aucune reproductibilité, seulement son
   poids. Deux plutôt qu'une, pour qu'une image cassée ait un recours. Les

{dsoxlab-0.2.2 → dsoxlab-0.2.4}/CHANGELOG.md

@@ -9,6 +9,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-09-26
+
+### Fixed
+
+- **The appliance build got one step further, and stopped on the step before.**
+  With `/mnt` finally writable, Packer refused to start: *Output directory
+  '/mnt/appliance/out' already exists. It must not exist.* That refusal is a
+  feature — it is how Packer guarantees it never writes over a previous
+  build — and the preparation step was creating that very directory. It now
+  creates only the parent and the temporary directory, and leaves `out/` to
+  Packer. Two failures in a row at the same place say something worth keeping:
+  a workflow that has never run is a workflow that does not work, and the only
+  way to know is to run it.
+
+## [0.2.3] - 2026-09-26
+
+### Fixed
+
+- **The appliance workflow had never run, and died four hundredths of a second
+  in.** `mkdir: cannot create directory '/mnt/appliance': Permission denied` —
+  on a GitHub runner `/mnt` belongs to root, and that is where the disk space
+  is (~70 GB against ~14 on `/`). No local build could show it, since the
+  directory exists and is writable on a developer's machine. A dedicated step
+  now creates it with `sudo` and hands it to the runner.
+
+- **The image is published on every release, not only on minor ones.** The old
+  rule saved bandwidth and cost more than it saved: the documentation announced
+  an appliance the latest release did not carry, and the reader had to work out
+  which earlier release did. "The latest release carries the image" is the only
+  sentence that needs no caveat, and nothing accumulates since the retention
+  step keeps the last two sets. The two workflows now start from the same tag,
+  so the upload waits for the Release to exist instead of assuming it — and
+  says which workflow to look at if it never does.
+
+### Changed
+
+- **The documentation is a path now, not a pile of pages.** Read end to end
+  against the code, it had breaks that no single page could reveal:
+
+  `learner.md` promised `run` right after cloning a catalog, while **66 of the
+  Linux catalog's 86 labs** are `vm` labs: that `run` exits 2, the `provision`
+  it suggests exits 1 for want of an SSH key, and neither `instructor
+  bootstrap`, nor `start`, nor the word Terraform appeared anywhere on the
+  page. It now names what a `vm` lab asks of a machine, and puts `start` first
+  — the command that plays the whole order and announces each step with the
+  command that replays it alone.
+
+  `catalog-author.md` listed a lab's files without saying what goes in them.
+  The scale that `validate-structure` enforces (`### … (20 pts)` against a
+  `N tasks, M points` header, and one point per test), the format of
+  `hints.yaml`, and where `conftest.py` lives — pytest runs from the catalog
+  root — were documented nowhere.
+
+  The README reached neither the index nor `exit-codes.md`,
+  `machine-output.md` and `infra-only.md`: three reference pages unreachable
+  from the front door.
+
+  The SSH key was described as something a catalog ships. It is not: published
+  catalogs ignore the whole `ssh/` directory, and `provision` refuses to start
+  without the private half. It is generated **per clone**, by `instructor
+  bootstrap`, learners included.
+
+  `contract-v1.md` contradicted itself nine lines apart on whether
+  `repo.category` is required.
+
+- **`docs/appliance.md` is a step-by-step**, from installing VirtualBox to the
+  first lab, with the digest check, the memory to give the machine depending on
+  the host's, what the first boot looks like in three acts, and a
+  troubleshooting table. Both READMEs open on the two ways in, each with its
+  own four-step path.
+
+### Added
+
+- **Credit where it is due**: the appliance is [@cedric-ribier]'s idea, and it
+  exists because he had already built one end to end and documented it in
+  [#91](https://github.com/stephrobert/dsoxlab/issues/91). The one shipped here
+  is directly inspired by his.
+
+[@cedric-ribier]: https://github.com/cedric-ribier
+
 ## [0.2.2] - 2026-09-26
 
 ### Added
@@ -27,8 +107,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
   The image **pins nothing**. The first boot installs the latest dsoxlab, and the
   hypervisors only if the host exposes nested virtualization — checked live, never
-  assumed. Which is why it is rebuilt on **minor tags only**: republishing half a
-  gigabyte for every patch would cost a lot and change nothing.
+  assumed. It is rebuilt on **every published version**, patches included: the
+  latest release carries the image, which is the only sentence that needs no
+  caveat. Nothing accumulates — only the last two sets are kept.
 
   Measured, not estimated: **461 MiB** for the qcow2 and **446 MiB** for the OVA,
   built in 4 min 50 s, against a budget the workflow enforces at 800 MiB. A
@@ -39,7 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   selling them as equals.
 
 - **Only the last two sets of images are kept on the Releases.** Roughly 900 MB
-  per minor version, forever, for images that pin no dsoxlab version and
+  per version, forever, for images that pin no dsoxlab version and
   install the latest at first boot: an old one offers no reproducibility, only
   weight. Two rather than one, so a broken image has a fallback. The Releases,
   their changelog and the Python distributions are untouched.

{dsoxlab-0.2.2 → dsoxlab-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dsoxlab
-Version: 0.2.2
+Version: 0.2.4
 Summary: Turn declarative exercises into reproducible, runnable and verifiable lab environments
 Project-URL: Homepage, https://blog.stephane-robert.info/
 Project-URL: Documentation, https://github.com/stephrobert/dsoxlab/blob/main/docs/README.md
@@ -118,9 +118,42 @@ and no Docker: it runs anywhere dsoxlab runs.
 
 ---
 
+## Or: the appliance, in four steps
+
+For Windows and macOS, where `uv tool install` is not an option. No knowledge
+of virtualization required.
+
+1. **Install VirtualBox** from <https://www.virtualbox.org/wiki/Downloads>. The
+   *Extension Pack* it offers is not needed.
+2. **Download the `.ova`** from the latest
+   [release](https://github.com/stephrobert/dsoxlab/releases) that carries one,
+   and check its digest against the `SHA256SUMS` published next to it.
+3. **Import and start**: in VirtualBox, *File → Import Appliance*, pick the
+   `.ova`, *Finish*, then *Start*. The first boot installs dsoxlab, the
+   hypervisors and the desktop, then **reboots on its own**: count five to
+   fifteen minutes, with nothing to type.
+4. **Log in** with `student` / `dsoxlab` — the machine requires you to change
+   that password, which is public — then, in the desktop's terminal:
+
+   ```bash
+   dsoxlab demo && cd ~/.local/share/dsoxlab/demo
+   dsoxlab course premiers-pas
+   ```
+
+`vm` labs need one more step, **nested virtualization**, which is enabled on
+your computer and not inside the machine: *Settings → System → Processor →
+Enable Nested VT-x/AMD-V*, appliance powered off. `dsoxlab doctor` says so when
+it is missing.
+
+Every step in detail, the actual requirements and a troubleshooting table are
+on **[the appliance page](docs/appliance.md)**.
+
+---
+
 ## Documentation
 
-Three readers, three doors. Every page names its audience in its first lines.
+Every page names its audience in its first lines, and
+[the index](docs/README.md) lists them all.
 
 | I want to… | Read |
 | --- | --- |
@@ -128,6 +161,8 @@ Three readers, three doors. Every page names its audience in its first lines.
 | Play labs on Windows or macOS, without installing anything | **[The appliance](docs/appliance.md)**, a ready-to-play VM |
 | Write my own catalog of labs | **[For the catalog author](docs/catalog-author.md)**, then [the v1 contract](docs/contract-v1.md) field by field |
 | Run the machines the labs need | **[For the trainer](docs/trainer.md)** |
+| Get throwaway VMs, with no exercise to write | [Infrastructure without labs](docs/infra-only.md) |
+| Call dsoxlab from a script or a CI, and branch on the result | [Exit codes](docs/exit-codes.md), then [the machine output](docs/machine-output.md) for `--json` |
 | Know where dsoxlab writes on my disk | [Where dsoxlab writes](docs/files.md) |
 | See every command | [Command reference](docs/commands.md), generated from the CLI |
 
@@ -217,6 +252,13 @@ persistent, and four releases come from his reports:
   ready-to-use appliance, discussed in
   [#91](https://github.com/stephrobert/dsoxlab/issues/91).
 
+**And the appliance itself is his idea.** He did not ask for it: he had already
+**built one end to end**, then documented it in
+[#91](https://github.com/stephrobert/dsoxlab/issues/91). The one dsoxlab ships
+today is directly inspired by his — the idea and the approach both. It is the
+contribution a changelog shows least and the product owes most: without it,
+there would be nothing to offer anyone working on Windows or macOS.
+
 **[@Gedd18](https://github.com/Gedd18)** found that the lab catalog's
 `conftest.py` failed to load whenever no infrastructure provider was resolved,
 which silently blocked **every `shell` lab** — the very first ones a learner

{dsoxlab-0.2.2 → dsoxlab-0.2.4}/README.fr.md

@@ -80,10 +80,43 @@ conteneur, ni Docker : il tourne partout où dsoxlab tourne.
 
 ---
 
+## Ou : l'appliance, en quatre étapes
+
+Pour Windows et macOS, où `uv tool install` n'est pas une option. Aucune
+connaissance de la virtualisation n'est nécessaire.
+
+1. **Installez VirtualBox** depuis
+   <https://www.virtualbox.org/wiki/Downloads>. L'*Extension Pack* proposé
+   n'est pas nécessaire.
+2. **Téléchargez le fichier `.ova`** de la dernière
+   [release](https://github.com/stephrobert/dsoxlab/releases) qui en porte un,
+   et vérifiez son empreinte avec le `SHA256SUMS` publié à côté.
+3. **Importez et démarrez** : dans VirtualBox, *Fichier → Importer un appareil
+   virtuel*, choisissez le `.ova`, *Terminer*, puis *Démarrer*. Le premier
+   démarrage installe dsoxlab, les hyperviseurs et le bureau, puis **redémarre
+   tout seul** : comptez cinq à quinze minutes, sans rien taper.
+4. **Connectez-vous** avec `student` / `dsoxlab` — la machine exige de changer
+   ce mot de passe, qui est public — puis, dans le terminal du bureau :
+
+   ```bash
+   dsoxlab demo && cd ~/.local/share/dsoxlab/demo
+   dsoxlab course premiers-pas
+   ```
+
+Les labs `vm` demandent une étape de plus, la **virtualisation imbriquée**, qui
+s'active sur votre ordinateur et non dans la machine : *Configuration → Système
+→ Processeur → Activer VT-x/AMD-V imbriqué*, appliance éteinte. `dsoxlab
+doctor` le dit s'il manque.
+
+Le détail de chaque étape, les prérequis chiffrés et un tableau de dépannage
+sont dans **[la page de l'appliance](docs/appliance.fr.md)**.
+
+---
+
 ## Documentation
 
-Trois lecteurs, trois portes. Chaque page nomme son public dès ses premières
-lignes.
+Chaque page nomme son public dès ses premières lignes, et
+[l'index](docs/README.fr.md) les répertorie toutes.
 
 | Je veux… | Lire |
 | --- | --- |
@@ -91,6 +124,8 @@ lignes.
 | Jouer des labs sous Windows ou macOS, sans rien installer | **[L'appliance](docs/appliance.fr.md)**, une VM prête à jouer |
 | Écrire mon propre catalogue de labs | **[Pour l'auteur de catalogue](docs/catalog-author.fr.md)**, puis [le contrat v1](docs/contract-v1.fr.md) champ par champ |
 | Monter les machines dont les labs ont besoin | **[Pour le formateur](docs/trainer.fr.md)** |
+| Obtenir des VM jetables, sans aucun exercice à écrire | [L'infrastructure sans labs](docs/infra-only.fr.md) |
+| Appeler dsoxlab depuis un script ou une CI, et décider sur le résultat | [Les codes de sortie](docs/exit-codes.fr.md), puis [la sortie machine](docs/machine-output.fr.md) pour `--json` |
 | Savoir où dsoxlab écrit sur mon disque | [Où dsoxlab écrit](docs/files.fr.md) |
 | Voir toutes les commandes | [Référence des commandes](docs/commands.fr.md), produite par la CLI |
 
@@ -186,6 +221,14 @@ et quatre versions viennent de ses remontées :
   une image prête à l'emploi, discuté dans
   [#91](https://github.com/stephrobert/dsoxlab/issues/91).
 
+**Et l'appliance elle-même est son idée.** Il ne l'a pas demandée : il l'avait
+déjà **construite de bout en bout**, puis documentée dans
+[#91](https://github.com/stephrobert/dsoxlab/issues/91). Celle que dsoxlab
+publie aujourd'hui s'inspire directement de la sienne — l'idée comme la
+démarche. C'est la contribution la moins visible dans un journal des
+modifications et la plus structurante pour le produit : sans elle, il n'y
+aurait rien à proposer à qui travaille sous Windows ou macOS.
+
 **[@Gedd18](https://github.com/Gedd18)** a trouvé que le `conftest.py` du
 catalogue de labs ne se chargeait plus dès qu'aucun provider d'infrastructure
 n'était résolu, ce qui bloquait en silence **tous les labs `shell`**, c'est-à-dire

{dsoxlab-0.2.2 → dsoxlab-0.2.4}/README.md

@@ -81,9 +81,42 @@ and no Docker: it runs anywhere dsoxlab runs.
 
 ---
 
+## Or: the appliance, in four steps
+
+For Windows and macOS, where `uv tool install` is not an option. No knowledge
+of virtualization required.
+
+1. **Install VirtualBox** from <https://www.virtualbox.org/wiki/Downloads>. The
+   *Extension Pack* it offers is not needed.
+2. **Download the `.ova`** from the latest
+   [release](https://github.com/stephrobert/dsoxlab/releases) that carries one,
+   and check its digest against the `SHA256SUMS` published next to it.
+3. **Import and start**: in VirtualBox, *File → Import Appliance*, pick the
+   `.ova`, *Finish*, then *Start*. The first boot installs dsoxlab, the
+   hypervisors and the desktop, then **reboots on its own**: count five to
+   fifteen minutes, with nothing to type.
+4. **Log in** with `student` / `dsoxlab` — the machine requires you to change
+   that password, which is public — then, in the desktop's terminal:
+
+   ```bash
+   dsoxlab demo && cd ~/.local/share/dsoxlab/demo
+   dsoxlab course premiers-pas
+   ```
+
+`vm` labs need one more step, **nested virtualization**, which is enabled on
+your computer and not inside the machine: *Settings → System → Processor →
+Enable Nested VT-x/AMD-V*, appliance powered off. `dsoxlab doctor` says so when
+it is missing.
+
+Every step in detail, the actual requirements and a troubleshooting table are
+on **[the appliance page](docs/appliance.md)**.
+
+---
+
 ## Documentation
 
-Three readers, three doors. Every page names its audience in its first lines.
+Every page names its audience in its first lines, and
+[the index](docs/README.md) lists them all.
 
 | I want to… | Read |
 | --- | --- |
@@ -91,6 +124,8 @@ Three readers, three doors. Every page names its audience in its first lines.
 | Play labs on Windows or macOS, without installing anything | **[The appliance](docs/appliance.md)**, a ready-to-play VM |
 | Write my own catalog of labs | **[For the catalog author](docs/catalog-author.md)**, then [the v1 contract](docs/contract-v1.md) field by field |
 | Run the machines the labs need | **[For the trainer](docs/trainer.md)** |
+| Get throwaway VMs, with no exercise to write | [Infrastructure without labs](docs/infra-only.md) |
+| Call dsoxlab from a script or a CI, and branch on the result | [Exit codes](docs/exit-codes.md), then [the machine output](docs/machine-output.md) for `--json` |
 | Know where dsoxlab writes on my disk | [Where dsoxlab writes](docs/files.md) |
 | See every command | [Command reference](docs/commands.md), generated from the CLI |
 
@@ -180,6 +215,13 @@ persistent, and four releases come from his reports:
   ready-to-use appliance, discussed in
   [#91](https://github.com/stephrobert/dsoxlab/issues/91).
 
+**And the appliance itself is his idea.** He did not ask for it: he had already
+**built one end to end**, then documented it in
+[#91](https://github.com/stephrobert/dsoxlab/issues/91). The one dsoxlab ships
+today is directly inspired by his — the idea and the approach both. It is the
+contribution a changelog shows least and the product owes most: without it,
+there would be nothing to offer anyone working on Windows or macOS.
+
 **[@Gedd18](https://github.com/Gedd18)** found that the lab catalog's
 `conftest.py` failed to load whenever no infrastructure provider was resolved,
 which silently blocked **every `shell` lab** — the very first ones a learner