commit a79b7705bd00980476ff56c3ba423363974ae1da
parent 85d10cae9070a26cd05dc6dd70c89b1c9140c21d
Author: triesap <tyson@radroots.org>
Date: Thu, 12 Mar 2026 20:28:12 +0000
docs: add nix onboarding guide
- document first-time nix installation and flake setup for the workspace
- explain the default, coverage, and release shell entrypoints and command map
- clarify the split between pure flake checks and repo-aware nix run workflows
- verify cargo check, cargo test, and docs diff hygiene for the docs-only change
Diffstat:
| A | docs/nix.md | | | 122 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 122 insertions(+), 0 deletions(-)
diff --git a/docs/nix.md b/docs/nix.md
@@ -0,0 +1,122 @@
+# Nix
+
+This workspace uses Nix as the canonical development and CI environment contract.
+
+## Install Nix
+
+macOS:
+
+```bash
+sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install)
+```
+
+Linux with systemd:
+
+```bash
+sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon
+```
+
+Enable flakes for your user:
+
+```bash
+mkdir -p ~/.config/nix
+cat > ~/.config/nix/nix.conf <<'EOF'
+experimental-features = nix-command flakes
+accept-flake-config = true
+EOF
+```
+
+## Optional direnv
+
+Install `direnv` and `nix-direnv` if you want the shell to load automatically when you enter the repo.
+
+```bash
+brew install direnv
+echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
+nix profile install nixpkgs#nix-direnv
+mkdir -p ~/.config/direnv
+echo 'source $HOME/.nix-profile/share/nix-direnv/direnvrc' >> ~/.config/direnv/direnvrc
+```
+
+After that:
+
+```bash
+direnv allow
+```
+
+## Enter The Shell
+
+Default shell:
+
+```bash
+nix develop
+```
+
+Coverage or release shell:
+
+```bash
+nix develop .#coverage
+nix develop .#release
+```
+
+The shells provide:
+
+- Rust `1.92.0` with `wasm32-unknown-unknown`
+- pinned nightly cargo for coverage
+- `wasm-pack`
+- `cargo-llvm-cov`
+- `pkg-config`
+- `clang` and `libclang`
+- `libsodium`
+
+## Command Map
+
+Pure flake checks:
+
+```bash
+nix flake check
+```
+
+Repo-aware command apps:
+
+```bash
+nix run .#fmt
+nix run .#check
+nix run .#contract
+nix run .#export-ts
+nix run .#coverage-report
+nix run .#wasm-builds
+nix run .#release-preflight
+nix run .#publish-dry-run
+nix run .#publish-crates -- --dry-run
+```
+
+`nix flake check` is intentionally limited to pure surfaces:
+
+- Nix, shell, and TOML formatting through `treefmt`
+- Rust formatting through `cargo fmt --check`
+- pure cargo check/test derivations for the contract crate set
+- repo guards that can run without cargo registry network access
+
+Repo-aware flows stay behind `nix run` apps because they need a real checkout:
+
+- `sdk export-ts` writes into repo-local `target/`
+- coverage refresh and release preflight produce repo-local artifacts
+- wasm packaging writes package output directories
+- publish commands read runtime tokens and the live checkout state
+
+## First Verification
+
+After installation:
+
+```bash
+nix flake check
+nix run .#contract
+nix run .#release-preflight
+```
+
+## Notes
+
+- Flakes only see tracked files when the source is treated as a git checkout. If Nix appears to miss a new file, `git add` it first.
+- Do not put secrets in `flake.nix`.
+- `publish-crates.sh` reads `CARGO_REGISTRY_TOKEN` or `CRATES_IO_TOKEN` from your runtime environment.
