Clarified Docker-first setup contract

Author: byteshiftlabs

CONTRIBUTING.md

@@ -15,8 +15,9 @@ Thank you for your interest in contributing to ThunderOS! This guide will help y
 
 3. **Set up your environment**
    - Follow setup instructions in [docs/source/development.rst](docs/source/development.rst)
-   - Install RISC-V toolchain and QEMU
-   - Build and test: `make && make qemu`
+   - Initialize submodules: `git submodule update --init --recursive`
+   - Run the authoritative verification path first: `make docker-verify`
+   - Use native `make`, `make qemu`, and `make debug` only after the Docker path is understood
 
 ## How to Contribute
 
@@ -64,8 +65,15 @@ Thank you for your interest in contributing to ThunderOS! This guide will help y
    - Target the current `dev/vX.Y.Z` branch
    - Write a clear PR description
    - Reference related issues
+   - Include the verification command you ran (`make docker-verify`, or explain why a narrower check was necessary)
    - Wait for review
 
+### Working With The Userland Submodule
+
+- `external/userland/` is versioned by the submodule commit recorded in this repository.
+- If your change requires userland work, commit and push the `thunderos-userland` change first, then update the submodule pointer here intentionally.
+- Before opening a PR that touches the submodule pointer, verify with `make docker-verify` from the ThunderOS root.
+
 ## AI Usage Policy
 
 ThunderOS uses AI assistance for development. See the [ai-dev-prompts](https://github.com/byteshiftlabs/ai-dev-prompts) repository for guidelines on:

Makefile

@@ -111,12 +111,14 @@ QEMU_FLAGS := -machine virt -m 128M -nographic -serial mon:stdio
 QEMU_FLAGS += -bios none
 QEMU_FLAGS += $(QEMU_ACCEL_FLAGS)
 QEMU_FLAGS += $(QEMU_EXTRA_FLAGS)
+DOCKER_IMAGE ?= thunderos-build:local
+DOCKER_USER ?= $(shell id -u):$(shell id -g)
 
 # Filesystem image
 FS_IMG := $(BUILD_DIR)/fs.img
 FS_SIZE := 10M
 
-.PHONY: all clean run debug fs userland test test-quick help
+.PHONY: all clean run debug fs userland test test-quick help docker-build-env docker-verify docker-shell
 
 # Default target - must be first
 all: $(KERNEL_ELF) $(KERNEL_BIN)
@@ -145,6 +147,9 @@ help:
 	@echo "  $(GREEN)make clean$(RESET)        Remove all build artifacts"
 	@echo "  $(GREEN)make userland$(RESET)     Build userland programs only"
 	@echo "  $(GREEN)make fs$(RESET)           Build ext2 filesystem image"
+	@echo "  $(GREEN)make docker-build-env$(RESET) Build the authoritative Docker toolchain image"
+	@echo "  $(GREEN)make docker-verify$(RESET)    Run clean build + test inside the Docker image"
+	@echo "  $(GREEN)make docker-shell$(RESET)     Open an interactive shell inside the Docker image"
 	@echo ""
 	@echo "$(BOLD)Run Targets:$(RESET)"
 	@echo "  $(GREEN)make run$(RESET)          Build and run in QEMU (text mode)"
@@ -296,6 +301,37 @@ test:
 test-quick:
 	@cd tests/scripts && bash test_runner.sh --quick
 
+docker-build-env:
+	@echo ""
+	@echo "$(BOLD)$(BLUE)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
+	@echo "$(BOLD)$(BLUE)  Building ThunderOS Docker Environment$(RESET)"
+	@echo "$(BOLD)$(BLUE)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
+	@docker build -t $(DOCKER_IMAGE) .
+	@echo "$(GREEN)✓ Docker image ready:$(RESET) $(DOCKER_IMAGE)"
+	@echo ""
+
+docker-verify: docker-build-env
+	@echo ""
+	@echo "$(BOLD)$(GREEN)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
+	@echo "$(BOLD)$(GREEN)  Running Authoritative Docker Verification$(RESET)"
+	@echo "$(BOLD)$(GREEN)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)"
+	@docker run --rm \
+		--user $(DOCKER_USER) \
+		-e HOME=/tmp/thunderos-home \
+		-v $(CURDIR):/workspace \
+		-w /workspace \
+		$(DOCKER_IMAGE) \
+		bash -lc "make clean && make && make test"
+
+docker-shell: docker-build-env
+	@docker run --rm -it \
+		--user $(DOCKER_USER) \
+		-e HOME=/tmp/thunderos-home \
+		-v $(CURDIR):/workspace \
+		-w /workspace \
+		$(DOCKER_IMAGE) \
+		bash
+
 qemu: userland fs
 	@rm -f $(BUILD_DIR)/kernel/main.o
 	@$(MAKE) --no-print-directory TEST_MODE=0 all

README.md

@@ -19,8 +19,17 @@ See [CHANGELOG.md](CHANGELOG.md) for complete feature list and [ROADMAP.md](ROAD
 ### Cloning
 ```bash
 git clone --recurse-submodules https://github.com/byteshiftlabs/thunderos.git
+cd thunderos
+git submodule update --init --recursive
 ```
 
+### Authoritative Verification
+```bash
+make docker-verify
+```
+
+This is the release-grade setup path. It builds the repository Docker image, uses the pinned RISC-V toolchain and QEMU 10.1.2 from that image, and runs `make clean && make && make test` inside the container.
+
 ### Building
 ```bash
 make clean && make
@@ -36,7 +45,7 @@ make OPT_LEVEL=-O2 DEBUG_SYMBOLS=1
 make qemu
 ```
 
-The OS will automatically build the filesystem image and start QEMU with VirtIO block device support.
+The OS will automatically build the filesystem image and start QEMU with VirtIO block device support. Native QEMU runs are a convenience path for local iteration; if your host toolchain or QEMU version differs from the Docker environment, use `make docker-verify` before treating the result as release-quality.
 
 For smoother local runs, you can override QEMU acceleration and extra flags:
 ```bash
@@ -64,6 +73,27 @@ riscv64-unknown-elf-gdb build/thunderos.elf
 (gdb) target remote :1234
 ```
 
+If your host toolchain does not match the Docker-verified environment, open the authoritative shell first and debug from there:
+
+```bash
+make docker-shell
+```
+
+## Setup Contract
+
+ThunderOS has two supported public setup paths:
+
+1. `make docker-verify`
+  This is the authoritative verification path used to mirror release gating. It relies on the repository Dockerfile, which pins the RISC-V bare-metal toolchain and QEMU 10.1.2.
+2. `make`, `make qemu`, `make debug`
+  This is the native Linux convenience path for day-to-day development when you already have a matching toolchain, `mkfs.ext2`, and QEMU 10.1.2+ on the host.
+
+If the native host path disagrees with Docker, Docker wins.
+
+## Versioning And Userland
+
+`external/userland/` is pinned by git submodule commit, not by a floating branch. Releases are expected to update that submodule intentionally, keep `git submodule status` clean, and pass `make docker-verify` before publishing. That is the contract that keeps kernel and userland changes versioned together.
+
 ## Documentation
 
 Full technical documentation is available in Sphinx format:
@@ -145,7 +175,10 @@ Programs are compiled as RISC-V ELF64 executables and can be loaded from the ext
 
 ## Platform Support
 
-- **QEMU virt machine**: Tested and working ✓
+- **Runtime target**: QEMU `virt` machine with 128 MiB RAM, `-bios none`, and VirtIO block storage
+- **Authoritative verification environment**: Repository Dockerfile with the pinned RISC-V toolchain and QEMU 10.1.2
+- **Native host development**: Supported as a convenience path when the host matches the documented toolchain requirements
+- **Real hardware**: Not a supported public target yet; bring-up work should be treated as experimental until documented otherwise
 
 ## Requirements
 

docs/source/development.rst

@@ -8,41 +8,38 @@ Building
 Prerequisites
 ~~~~~~~~~~~~~
 
-**Option 1: Using Docker (Recommended)**
+**Option 1: Using Docker (Authoritative Verification Path)**
 
-The easiest way to build ThunderOS is using Docker, which provides a consistent build environment:
+The repository Dockerfile is the authoritative release-verification environment. It provides the pinned RISC-V bare-metal toolchain, QEMU 10.1.2, and the documentation dependencies used by CI.
 
 .. code-block:: bash
 
-   # Build the Docker image
-   docker build -t thunderos-build .
-   
-   # Build ThunderOS in Docker
-   docker run --rm -v $(pwd):/workspace -w /workspace thunderos-build make all
-   
-   # Run in QEMU via Docker
-   docker run --rm -v $(pwd):/workspace -w /workspace thunderos-build make qemu
+   make docker-verify
 
-**Option 2: Native Installation (Ubuntu/Debian)**
+For an interactive shell inside that same environment:
 
 .. code-block:: bash
 
-   # QEMU (for emulation)
-   sudo apt-get install qemu-system-misc
-   
-   # Build tools
-   sudo apt-get install build-essential make wget
-   
-   # RISC-V toolchain (manual installation required)
-   # Download from SiFive or build from source
-   wget https://static.dev.sifive.com/dev-tools/freedom-tools/v2020.12/riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14.tar.gz
-   tar -xzf riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14.tar.gz
-   sudo mv riscv64-unknown-elf-toolchain-10.2.0-2020.12.8-x86_64-linux-ubuntu14 /opt/riscv
-   export PATH="/opt/riscv/bin:$PATH"  # Add to ~/.bashrc
-   
-   # Verify installation
+   make docker-shell
+
+**Option 2: Native Linux Convenience Path**
+
+Native builds are intended for day-to-day development once you already have a matching toolchain installed. If native behavior disagrees with Docker, treat Docker as authoritative.
+
+.. code-block:: bash
+
+   git submodule update --init --recursive
    riscv64-unknown-elf-gcc --version
    qemu-system-riscv64 --version
+   make clean && make
+   make test
+
+The native path requires:
+
+- ``riscv64-unknown-elf-gcc`` on ``PATH``
+- ``qemu-system-riscv64`` 10.1.2 or newer
+- ``mkfs.ext2`` from ``e2fsprogs``
+- standard Unix build tools (``make``, ``bash``, ``sed``)
 
 **Option 3: Using Build Scripts (After Setup)**
 
@@ -58,7 +55,7 @@ Once prerequisites are installed:
 Compilation
 ~~~~~~~~~~~
 
-**Using Build Scripts (Recommended)**
+**Using Build Scripts (Native Convenience Path)**
 
 .. code-block:: bash
 
@@ -82,6 +79,9 @@ Compilation
    # Debug with GDB
    make debug
 
+   # Authoritative Docker verification
+   make docker-verify
+
 Testing
 -------
 
@@ -129,10 +129,8 @@ To run similar tests locally:
 
 .. code-block:: bash
 
-   # Build and test (mimics CI)
-   docker build -t thunderos-build .
-   docker run --rm -v $(pwd):/workspace -w /workspace thunderos-build make clean && make
-   docker run --rm -v $(pwd):/workspace -w /workspace thunderos-build make test
+   # Build and test through the same Docker image used for release verification
+   make docker-verify
 
 
 Debugging