Audience: this page is a switchboard, and belongs to no one in particular. Every other page names its reader in its first lines, because a document that answers three people at once answers none of them.
dsoxlab turns declarative exercises into reproducible, runnable and verifiable
lab environments. The repository README says what it is in
thirty seconds; these pages say how it works.
| Page | For you if… |
|---|---|
| For the learner | You install dsoxlab, play labs and want to understand your score |
| For the catalog author | You write labs in your own repository |
| For the trainer | You run the machines and providers the labs need |
There is a fourth door for those who would rather not install anything: the appliance, a ready-to-play virtual machine, for Windows and macOS.
| Page | Content |
|---|---|
| The v1 contract | meta.yml and lab.yaml, field by field, with what version 1 guarantees |
| Command reference | Every command, generated from the CLI itself |
| Where dsoxlab writes | Every file dsoxlab creates, and the environment variables it reads |
| Infrastructure without labs | Using dsoxlab as a provisioner of throwaway VMs, without writing a single exercise |
| The machine output | What --json prints, field by field, and what may be built on it |
| Exit codes | Every code the CLI returns, what it means, and the gesture it calls for |
| The security model | Where the trust boundary runs, what the engine refuses to do, and what it does not protect you from |
| Design principles | The invariants, each with the incident that revealed it and the test that holds it — and what the project promises to whoever integrates it |
| Architecture decisions | Why each durable choice was made: its context, what was rejected, what it costs and what would reverse it |
| The mark | Name, logo and their usage terms |
Contributors have CONTRIBUTING.md: setup, quality gates, architecture map and commit conventions.
Nothing here is written twice. The command table is generated from the CLI,
and the file locations are checked against the code by
tests/test_documentation_synchrone.py, which derives them by calling the same
functions the CLI calls. Both controls exist because both had already drifted:
the command table described a cleanup.sh the contract forbids, and the
persistence section pointed at a database that never existed.
These pages are Markdown in the repository, deliberately. There is no site generator here, so the documentation is read where it is written, versioned with the code that it describes, and reviewed in the same pull request.