FDS/OS 1.0

tools/release-readme.md

@@ -0,0 +1,79 @@
+# FDS/OS 0.1.0 local release
+
+This directory contains versioned images, exact build inputs and a signed
+manifest. Physical Pi, NVMe, monitor and power validation is **deferred**. This
+release has not been installed or published automatically.
+
+## Verify the files first
+
+Use an already trusted build of `fds-release` and a public key obtained through
+an independently trusted channel. The bundled `signer.pub` alone does not
+establish the publisher's identity. From the parent of this release directory:
+
+```sh
+/path/to/trusted/fds-release verify fds-os-0.1.0 --key /path/to/trusted/signer.pub
+```
+
+Substitute the actual directory name. Success reports `VERIFIED FDS/OS 0.1.0`
+and checks every file listed in `manifest.json`. See `RELEASE-VERIFICATION.md`
+for the signature format and how to build the verifier from trusted source.
+
+## Choose the images
+
+| File | Destination/purpose |
+| --- | --- |
+| `fds-internal-0.1.0.img` | Complete internal NVMe disk: BOOT, independent RECOVERY and machine settings |
+| `fds-system-cli-0.1.0.img` | Removable SYSTEM cartridge with the ordinary FDS console and base Dasung controller |
+| `fds-system-development-0.1.0.img` | Alternative SYSTEM with native compilers, debugging tools and display diagnostics |
+| `fds-boot-0.1.0.img`, `fds-recovery-0.1.0.img` | Component partition payloads; normally use the complete internal disk above |
+| `fds-initramfs-0.1.0.cpio*`, kernel and device-tree files | Boot components already included in the internal disk |
+| `eeprom-production-*` | Reviewed EEPROM preparation/rollback files; the defaults are not a backup of your Pi |
+| `fds-*.xbps` | FDS base packages used to build the images; the running SYSTEM remains immutable |
+
+Use one internal disk and one of the two SYSTEM alternatives. Installation
+erases the selected target disks. Follow `INSTALLATION.md` for target identity,
+readback and first-boot steps, and `EEPROM.md` for the separately reviewed EEPROM
+procedure. The initial bay map is empty until actual wiring is calibrated.
+
+## Read the complete guides
+
+After verifying the release, extract the source archive into a new directory
+inside this release directory:
+
+```sh
+mkdir source
+tar --extract --zstd --same-permissions --no-same-owner \
+  --file fds-source-0.1.0.tar.zst --directory source
+```
+
+Start with [the project overview](source/README.md),
+[installation](source/docs/internal-storage.md), and
+[everyday cartridge use](source/docs/cartridges.md). The copied standalone guides
+retain their source-relative cross-references; the copies under `source/docs/`
+provide the complete linked documentation.
+
+## Rebuild from the preserved inputs
+
+`reproducibility.json` records the comparison of the two independent builds.
+`build-inputs.json` lists the exact snapshot contents, and `packages-*.json`
+records each profile's package versions and hashes. The complete input archive
+includes the compiler/toolchain, package files and pinned Void source bundle;
+the smaller source archive alone does not provide those dependencies.
+
+On the documented Arch build host, from this release directory:
+
+```sh
+mkdir inputs
+tar --extract --zstd --same-permissions --no-same-owner \
+  --file fds-build-inputs-0.1.0.tar.zst --directory inputs
+python3 inputs/project/tools/frozen-inputs verify "$PWD/inputs"
+python3 inputs/project/tools/frozen-inputs restore "$PWD/inputs" "$PWD/rebuild"
+rebuild/tools/in-frozen-build make all >rebuild.log 2>&1
+```
+
+Use new directories and paths without whitespace. The restored build has its
+recorded modes preserved by `--same-permissions`; `--no-same-owner` keeps the
+files owned by the ordinary build user. Its compiler and package environment use
+their own caches and have no network access. Host prerequisites and additional comparison
+instructions are in [Offline rebuilds](source/docs/reproducible-builds.md).
+The private signing key is not included in this release or its input archive.