commit 021ef4a5d7edbce042329662d7cf246deaae04ca
Author: jochen <jschoubben@gmail.com>
Date:   Sun Aug 23 22:25:58 2026 +0200

    mesh-lab: what this is, and why it is built first
    
    The node host takes over a machine's packages, services and network, so it
    cannot be developed against a machine anyone needs. The place to develop it
    has to exist before it does — which makes this phase 0, ahead of every tier
    it will later test.
    
    Two scenario classes, per ADR 0029. Bootstrap is virtual machines, the host
    and a pinned bundle, with the verdict coming from what the host reports
    about the state it reconciled. Full is a complete mesh with a pipeline.
    Bootstrap is a strict subset, so the full scenario is reached by putting
    more inside the machines rather than by building a second thing.
    
    Nothing here requires a forge, a coordinator or a pipeline to be useful.
    
    Decisions live in novox/hq. This repository carries implementation.

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..af4783d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# mesh-lab
+
+The lab: a disposable Novox Mesh on one machine.
+
+It ships to nobody. It runs on a workstation, raises virtual machines, puts things inside
+them, and throws them away.
+
+## Why it exists first
+
+The node host takes over a machine's packages, services and network. It cannot be developed
+against a machine anyone needs — so the place to develop it has to exist before it does.
+
+That makes this repository **phase 0** of the migration, ahead of every tier it will later
+test.
+
+## Two classes of scenario
+
+|  | **Bootstrap** | **Full** |
+|---|---|---|
+| Contains | virtual machines, the node host, a pinned substrate bundle | a complete mesh: forge, control plane, delivery, modules |
+| Verdict from | what the host reports about the state it reconciled | a pipeline result ending in verify |
+| Exercises | tiers 0 and 1 | tier 2 and above, and modules |
+| Exists to | **develop the mesh** | **test what runs on it** |
+
+The bootstrap scenario is a **strict subset** — same virtualisation, same networking, same
+lifecycle, stopping before a control plane exists. The full scenario is reached by putting more
+inside the machines, not by building a second thing.
+
+**Bootstrap is what gets built here first.** Nothing in this repository requires a forge, a
+coordinator or a pipeline to be useful.
+
+## Shape
+
+```
+scenarios/     declarations of a mesh to raise
+lifecycle/     create · snapshot · reset · destroy
+network/       segments and addressing
+place/         getting a binary onto a machine
+```
+
+Of the two jobs a runner might hold, **scenario lifecycle comes first** — something must
+materialise and reset a mesh before anything can be written against it. **Assertion execution
+comes later**, with the full scenario.
+
+## Rules
+
+- **Nothing new drives delivery.** A full scenario runs the real pipeline against a mesh named
+  by the request. A second delivery path would be blind to exactly the faults worth catching.
+- **A scenario starts from nothing, every time.** Adopting a machine that already exists is out
+  of scope — that is what makes a scenario a fixture rather than a snapshot.
+- **The real topology is one scenario among many**, not the baseline. Anything only testable
+  against the shape the mesh happens to have is a gap in the vocabulary.
+
+## Where the reasoning lives
+
+Design and decisions are in [`novox/hq`](https://git.novox.be/novox/hq), not here:
+
+- `03-DESIGN/01-to-be/01-end-to-end-testing.md` — the design
+- `02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md` — a lab node is a virtual machine
+- `02-DECISIONS/0029-the-labs-first-scenario-has-no-pipeline.md` — two scenario classes, and why this is first
+- `02-DECISIONS/0030-the-repository-structure.md` — why this is its own repository
+
+This repository carries implementation. It does not carry decisions.