Define Rust environment and toolchain

docs/ENVIRONMENT.md

@@ -0,0 +1,74 @@
+# Rust Development Environment
+
+## Pinned baseline
+
+[rust-toolchain.toml](../rust-toolchain.toml) pins Rust **1.97.1**, the minimal
+profile, and `rustfmt`/`clippy`. The native development host is
+`x86_64-unknown-linux-gnu`; the additional `x86_64-unknown-linux-musl` target is
+for executables running in Alpine integration containers. The host target is
+implicitly included by rustup. Do not force all Cargo builds to musl.
+
+Use Rust edition 2024 when creating Cargo.toml. Set its `rust-version` to
+`1.97.1` as the initial supported compiler floor; this is distinct from the
+exact toolchain pin. Do not claim compatibility with older compilers without
+testing it. Keep Cargo.lock tracked once the package exists.
+
+## Toolchain selection
+
+With rustup-managed Cargo/rustc proxies, entering the repository selects the
+toolchain file and may download missing components. Check `rustup show` and
+`rustup target list --installed`; explicit overrides may take precedence.
+Do not automatically install a global toolchain or modify the user's PATH.
+
+This host currently uses system-packaged tools under `/usr/bin`, without
+`rustup`. Such binaries do not enforce rust-toolchain.toml. Before execution,
+verify the installed compiler and Cargo match the pin, and that formatter and
+Clippy are available. If versions differ, stop the affected build and report
+the mismatch rather than silently updating the pin.
+
+Checks available before Cargo scaffolding:
+
+```sh
+rustc -Vv
+cargo -V
+rustfmt --version
+cargo clippy --version
+```
+
+After scaffolding, use the completion commands in [AGENTS.md](../AGENTS.md).
+The first dependency resolution generates Cargo.lock; subsequent checks use
+`--locked`. Registry access or a populated cache is required for dependencies.
+
+## Alpine target
+
+The toolchain file requests the musl Rust standard library; it does not supply
+all native compilers/linkers needed by a cross build. Establish the musl linker
+and any C dependency requirements before milestone 8, or build in a dedicated
+Alpine/musl builder. Keep build tools out of the small runtime test image.
+
+Once prerequisites and Cargo scaffolding exist, the planned cross-build check is:
+
+```sh
+cargo build --locked --release --target x86_64-unknown-linux-musl
+```
+
+Then run the built executable in Alpine and inspect actual dynamic-library
+requirements. A target name alone is not evidence that the binary runs there.
+Musl readiness is a milestone 8 prerequisite, not a milestone 1 acceptance gate.
+
+## Observed preparation state
+
+During preparation, local commands reported:
+
+- rustc: `1.97.1`, host `x86_64-unknown-linux-gnu`.
+- Cargo: `1.97.1`.
+- rustfmt: `1.9.0-stable`.
+- Clippy: `0.1.97`.
+- `rustup` and `musl-gcc`: not found in PATH.
+- The musl standard library directory reported by rustc does not exist.
+
+No toolchain, component, target, or native package installation was performed.
+These observations establish tool availability, not a successful project build.
+Recheck the environment at execution time.
+
+Reference: [rustup toolchain files and overrides](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file).