fds-os/AGENTS.md

FDS/OS implementation scope

The authoritative documentation lives in the fds-os.wiki submodule. Edit its flat Gitea Markdown pages directly; do not recreate a parallel manual or export workflow. Read fds-os.wiki/Gitea-Wiki.md for page and link conventions.

Read fds-os.wiki/Developer-Master-Plan.md and fds-os.wiki/Developer-Build-Host.md before changing the build. The user has explicitly authorized implementation through M12. Proceed through the remaining milestones in order, keeping the repository buildable and recording actual acceptance evidence. Defer tests that require the physical Raspberry Pi or its attached hardware; implement the corresponding software and hardware-test procedures, and never substitute VM results for physical measurements. Empty future component directories are intentional until their implementation; do not fill them with placeholder implementations that claim to work.

The user explicitly authorized importing the existing Paperlike 13K dasungd into the base system. Its Rust workspace member, static ARM package, base package selection, and native s6 service are required throughout M0–M12. Keep it in the base boot bundle, independent of GUI or ENVIRONMENT cartridges. Read fds-os.wiki/Dasung.md before changing it; do not claim Pi boot or physical power-cycle recovery is verified.

• Use English for all project-owned documentation, comments, diagnostics, task summaries, and conversation. Keep the master plan and build context in English.
• General userspace and XBPS target architecture: aarch64 + glibc.
• FDS executables: Rust + static aarch64-unknown-linux-musl by default.
• Use Clap for every Rust command-line interface, including test helpers. Define commands and options with typed parsers; do not hand-parse argument vectors.
• No systemd, runit, BusyBox, shell PID1, boot-time cache compilation, or sleeps to hide races in the target system.
• Keep vendor/void-packages clean and pinned. Use .host/void-packages for generated build state; keep authoritative FDS overlays in packages/.
• Explain every new dependency and keep documentation accurate.
• Run make bootstrap, make smoke-test, and make check for M0 build changes. Report skips and missing hardware honestly. Do not invent boot benchmarks.
• Run make rootfs PROFILE=cli and make rootfs-test for M1 composition changes. M2 adds native init. Run make init-test to verify PID 1 and service control in the isolated ARM virtual machine. The VM kernel is a test fixture, not a Pi image.

Workstation software and emulator follow-up

Read fds-os.wiki/Workstation.md, fds-os.wiki/Software-Format.md and fds-os.wiki/Developer-Workstation-Tooling-Plan.md for this extension. Software builds and new PROGRAM cartridge creation run on generic Linux workstations. The public native Clap tools are fds-cartridge and fds-emulator. Software images have GPT metadata partition 1 plus m EROFS payload partitions containing installed Void package trees. Build source templates with xbps-src on the workstation; do not create new xz software bundles or extract programs at guest launch. Keep legacy reading and base Dasung integration. Do not mutate the frozen 0.1.0 release or treat its historical acceptance as evidence for changed sources. Validate with make workstation-test and make emulator-test plus relevant guest checks.