fds-os/docs/README.md

# Documentation guide

FDS/OS builds bootable ARM SYSTEM images, an internal NVMe disk, independent
recovery, and a development environment. Native s6 manages the base system,
including Dasung support; cartridge tools manage DATA, programs and optional
desktop/network activation. M0–M12 software checks and local release
verification have passed. Physical Pi validation is deferred. The guides
below explain how to build, use and test the implemented system.

## If this is your first visit

1. Read the [project overview](../README.md) for the intended computer and current capabilities.
2. Follow [Your first build](getting-started.md) to create and inspect the working artifacts.
3. Read [Architecture](architecture.md) to understand the relationship between the build host, Linux packages, FDS tools, and cartridges.
4. Use the [Development guide](development.md) for subsequent changes and rebuilds.

The [Glossary](glossary.md) explains terms such as ABI, sysroot, EROFS, and
masterdir. No prior Void or s6 experience is assumed by the first-build guide.

## Working with the repository today

| Guide | Question it answers |
| --- | --- |
| [Workstation and emulator](workstation.md) | How do I build software, create a 1+m cartridge image, boot FDS, insert/remove it and write USB? |
| [Software cartridge format](software-format.md) | What goes in metadata, payload partitions and xz tarballs, and how does the guest run them? |
| [Workstation validation](workstation-validation.md) | Which host builds, whole-image writes and public QEMU lifecycle tests actually passed? |
| [Your first build](getting-started.md) | What do I install, what do I run, and how do I know it worked? |
| [M1 root filesystem](rootfs.md) | How do I build the OS filesystem, run its ARM shell, inspect packages, and test the archive? |
| [FDS Rust tooling](tooling.md) | How do I build and run the static FDS command and boot-discovery tools? |
| [Clap migration validation](clap-validation.md) | Which parser, complete-image, VM and startup checks passed after standardizing the Rust command lines? |
| [Internal storage](internal-storage.md) | How do I build the full NVMe disk, persist bay settings and save diagnostics? |
| [Release signatures](releases.md) | How do I create a signing key, sign artifacts and verify a download with a trusted key? |
| [Frozen inputs and offline rebuilds](reproducible-builds.md) | How do I preserve inputs, build without network access, compare results and assemble a local release? |
| [Boot images](boot.md) | How do I create the Pi boot partition, initramfs and SYSTEM cartridge, and test insertion/recovery? |
| [Desktop, PROGRAM and Ethernet](desktop.md) | How do I start WindowMaker, run cartridge programs, and enable networking? |
| [Media tools](media-tools.md) | How are images created, inspected and confirmed before cartridge writes? |
| [Pi 5 EEPROM configuration](eeprom.md) | How do I prepare, review and restore bootloader settings without flashing the build host? |
| [Twelve-bay stress tests](stress-testing.md) | How do I run the twelve-device VM checks and prepare physical tests? |
| [Shutdown and reboot](power.md) | How does shutdown protect DATA, and what should I do when it is blocked? |
| [Writable DATA](data.md) | Where do user files live, how do managed programs work, and when is removal safe? |
| [Implementation through M12](implementation-status.md) | What is complete, pending, and deferred to physical hardware? |
| [M12 software evidence](m12-validation.md) | Which checks, offline comparisons and signed local artifacts establish M12 software acceptance? |
| [Native init and ARM VM](init.md) | How do I boot the system, open its shell, and start or stop a service? |
| [M1 validation](m1-validation.md) | What did the original rootfs milestone verify? |
| [M2 validation](m2-validation.md) | Which full ARM boot and service-control checks passed? |
| [M3 validation](m3-validation.md) | Which static tooling and ARM parsing/discovery checks passed? |
| [M4 software validation](m4-validation.md) | Which image, module, stage0, insertion and recovery tests passed? |
| [M5 software validation](m5-validation.md) | Which ordinary-console, trace, emulation and optimization checks passed? |
| [M6 software validation](m6-validation.md) | Which virtual USB, mapping, metadata, mount, IPC and eject checks passed? |
| [M7 DATA validation](m7-validation.md) | Did sustained writes survive safe eject, reinsertion and independent filesystem checks? |
| [M8 desktop/network validation](m8-validation.md) | Did desktop transitions, PROGRAM execution, fonts and Ethernet work in the ARM VM? |
| [M9 media-tool validation](m9-validation.md) | Did ARM image creation, confirmed cartridge writes, verification and boot of a newly written SYSTEM pass? |
| [M10 shutdown validation](m10-validation.md) | Which ordered halt/reboot, busy refusal, crash and writeback-error tests passed? |
| [M11 stress validation](m11-validation.md) | Which twelve-device and media failure tests have passed, and what remains? |
| [Build host reference](build-host.md) | Which versions, dependencies, environment settings, and checks does the pipeline use? |
| [Development](development.md) | How do I rebuild only the component I changed, configure the build, and prepare a change? |
| [Dasung monitor](dasung.md) | How is the existing monitor daemon built, packaged, configured, and tested for the base system? |
| [Dasung validation](dasung-validation.md) | Which builds, simulator cases, and native s6 checks actually passed? |
| [Packages](packages.md) | What is an XBPS package, and how do I inspect the one I built? |
| [Troubleshooting](troubleshooting.md) | Why did a command fail, and what should I check next? |
| [M0 validation](m0-validation.md) | What has actually been built and verified on the development host? |

## Understanding the operating system

These pages explain the implemented behavior and distinguish software evidence
from properties that still need physical hardware tests.

| Guide | Subject |
| --- | --- |
| [Architecture](architecture.md) | Machine model, two library strategies, host/target split, writable state |
| [Boot](boot.md) | From internal NVMe to a removable SYSTEM and the first console |
| [Cartridges](cartridges.md) | Cartridge classes, physical bays, insertion, ejection, and manifests |
| [Services](services.md) | Native s6, service dependencies, readiness, and shutdown |
| [Performance](performance.md) | Timing targets, measurement boundaries, and regression reporting |
| [Recovery](recovery.md) | Build and enter independent recovery, inspect cartridges, check/repair DATA and prepare replacement SYSTEM media |

## Planning and reference

- [Roadmap](roadmap.md): current milestone, remaining milestones, and acceptance criteria.
- [Master plan](master-plan.md): the complete 67-section specification; examples describe the final design unless stated otherwise.
- [Project instructions](../AGENTS.md): implementation scope and conventions.

A `sh` code block in a current-workflow guide is intended to be run from the
repository root unless the surrounding text says otherwise. Planned runtime
examples use `text` blocks and are labeled as future behavior. Run build commands
sequentially; they share one Void build directory.