[wx8z]

Summary

• make the published Docker builder the recommended build path
• add macOS instructions: build through Docker Desktop and run the Docker-built raw disk image with host QEMU
• remove unsupported scons deps, scons toolchain, scons run, and scons debug documentation
• replace stale Documents/ links with Documentation/
• document direct QEMU/GDB helper scripts as manual advanced usage

Intentionally excluded

• no SCons aliases or build-system behavior changes
• no native macOS build support and no Homebrew build dependency path
• no dry-run validation claims
• Windows instructions are deferred beyond a short future-path note

Validation

• PATH="/Users/landen/.gem/ruby/2.6.0/bin:$PATH" make -C Documentation html
• docker run --rm -v "$PWD:/build" -w /build vincent4486/valeciumos-builder:i686 scons -Q BuildArch=i686 BuildType=kernel
• docker run --rm -v "$PWD:/build" -w /build vincent4486/valeciumos-builder:i686 scons -Q BuildArch=i686 BuildType=usr
• docker run --rm -v "$PWD:/build" -w /build vincent4486/valeciumos-builder:i686 scons -Q BuildArch=i686 ImageFormat=iso
• docker run --rm -v "$PWD:/build" -w /build vincent4486/valeciumos-builder:i686 scons -Q BuildArch=i686 ImageFormat=img
• qemu-system-i386 -m 4G -machine pc -smp 1 -device VGA,vgamem_mb=64 -drive file=build/i686_debug/valeciumos-0.28_debug_i686.img,format=raw,if=ide,index=0,media=disk -debugcon stdio started successfully on macOS and mounted the VALECIUM root filesystem before being terminated
• checked docs text does not reintroduce unsupported SCons aliases or native macOS build claims

[Copilot]

Pull request overview

Updates project documentation to make the published Docker builder the recommended, reproducible build workflow and removes/rewrites stale or unsupported build/run instructions.

Changes:

• Updates README.md quick start to use the Docker builder image and fixes stale Documents/ links to Documentation/.
• Rewrites Documentation/building.ad to focus on the Docker-first workflow, clarifies host-build expectations, and documents direct QEMU/GDB helper script usage.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
README.md	Switches quick-start to Docker builder usage; updates documentation links and notes about run/debug.
Documentation/building.ad	Replaces prior deps/toolchain/run/debug guidance with Docker-first build steps, host-build notes, configuration reference, and manual QEMU/GDB usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

These Docker builder examples mount the repo and run as root inside the container (the published image appears to be built from scripts/Dockerfile.* without switching users), which commonly leaves build/ and .config owned by root on the host. Consider adding a note and/or example using --user "$(id -u):$(id -g)" (and setting HOME) to prevent permission problems.

[Copilot]

This page states that SCons does not provide run/debug targets, but Documentation/devel.ad still documents scons debug (e.g., around line 43). That makes the docs inconsistent and conflicts with the PR goal of removing unsupported scons debug documentation; update/remove the scons debug mention in the developer guide (or adjust this section if scons debug is actually supported).

[Copilot]

The Docker builder image runs as root (see scripts/Dockerfile.i686), so these docker run ... -v "$PWD:/build" commands will typically create/modify build/ and .config as root-owned files on the host. Consider documenting a --user "$(id -u):$(id -g)" (and possibly -e HOME=/tmp) variant to avoid permission issues for developers.