distribution: establish the OS release contract

distribution/README.md

@@ -0,0 +1,45 @@
+# SouveraineOS distribution contract
+
+`SouveraineOS` is the operating-system repository. This directory is its
+release and installation authority.
+
+`../souveraine` is one component: the agent substrate, shell, and the package
+that delivers it. `../Pixel3Arch` is another: device packages and the blueline
+kernel. Neither decides what a SouveraineOS body is, what it installs, or where
+its release lands. Those decisions live here, once.
+
+## What this owns
+
+- `manifest.toml` is the canonical body, package, producer, and installer
+  profile graph.
+- The signed `edge` archive is one multi-producer archive. Its implementation
+  currently lives in `souveraine/packaging/arch/publish-edge.sh`; this manifest
+  names it so consumers do not grow their own publisher.
+- `../tools/validate-distribution.py` checks graph integrity without requiring
+  a runner, a device, or a secret.
+- `.gitea/workflows/distribution.yml` makes that check a gate in the OS repo.
+
+The manifest is deliberately honest about maturity. A profile marked `blocked`
+is a desired composition with named missing work, not an installer claim. Only
+a `ready` profile is eligible for a public installer or release channel.
+
+## The install shape
+
+An eventual graphical installer can be Calamares-shaped, but it must not own a
+second device matrix. It selects one target ID from this manifest, obtains that
+profile's signed packages, applies only its declared boot and device packages,
+then runs the target's commissioning step. The UI is downstream of this file.
+
+The first implementation remains a non-destructive provisioner: resolve a
+target, verify that its profile is `ready`, and emit the exact package and boot
+plan. Partitioning, credential enrollment, and device-local secrets require
+their own explicit installer work.
+
+## Producer rule
+
+Component workflows build code; they do not independently choose the release
+set. A producer may publish only package names and architectures declared here.
+The next pipeline change is to make each producer fetch this manifest at the
+commit carried by its build and reject an undeclared package before
+`publish-edge.sh` runs. That is how a new body becomes one profile and package
+change here, rather than another private chain of scripts.