build: replace flake.nix with a Kaifile

.envrc

@@ -1,3 +1,3 @@
-# direnv's `use flake` also uses nix-direnv when its hook is installed.
 # Never load .env or staging credentials in the development shell.
-use flake
+watch_file Kaifile.roc .kai/lock.json
+direnv_load kai shell default -- direnv dump

.gitignore

@@ -9,3 +9,7 @@ __pycache__/
 /dist/
 .env
 /docs/issues/
+
+# kai update writes the root lock; the rest of every .kai is generated.
+/.kai/*
+!/.kai/lock.json

AGENTS.md

@@ -108,8 +108,9 @@ Write one directory per issue, `docs/issues/<YYYY-MM-DD>-<short-slug>/`, with a
 4. **Status on other branches**: work is often on unmerged branches. Look at them
    (`git branch -a --no-merged origin/master`) and name any branch that fixes or reduces
    the issue.
-5. **Reproduction**: a reproducible setup in a `repro.sh` that runs in the Nix dev shell
-   (`nix develop --command ./docs/issues/<dir>/repro.sh`). Pin the commit it builds and
+5. **Reproduction**: a reproducible setup in a `repro.sh` that runs with the pinned
+   toolchain from `rust-toolchain.toml` (rustup, or on Linux the Kai shell:
+   `kai shell default -- ./docs/issues/<dir>/repro.sh`). Pin the commit it builds and
    use `scripts/voltage-local` or `scripts/voltage-staging` with placeholders for
    account-specific IDs. When the issue needs live state, such as an empty wallet, give
    the steps that create that state.

Kaifile.roc

@@ -0,0 +1,25 @@
+# Voltage CLI development shell (not a release package). `kai shell` enters it.
+# The Rust toolchain comes from rust-toolchain.toml, as it does for rustup and CI.
+app [kaifile] {
+	pf: platform "https://github.com/thebrandonlucas/kai/releases/download/v0.0.9/EenHNXeRqmvf2kHJLLbjroXeLwbQxyH5fbVQVgD3DXg4.tar.zst",
+	std: "https://github.com/thebrandonlucas/kai/releases/download/v0.0.9/std-DiShoF1FRWjQe7BmRnSTmqG44WgHUGuMMTMgBoaBqemq.tar.zst",
+}
+
+import std.Std
+
+import "rust-toolchain.toml" as toolchain : Str
+
+kaifile = Std.kaifile([
+	Name("voltage-cli"),
+	Systems(["x86_64-linux", "aarch64-linux"]),
+	Overlay("rust", "github:oxalica/rust-overlay"),
+	Environment(
+		"dev",
+		[
+			RustToolchain(toolchain),
+			Overlays(["rust"]),
+			Tools(["python3", "cargo-machete"]),
+		],
+	),
+	Shell("default", [Use("dev")]),
+])

docs/development.md

@@ -27,39 +27,34 @@ git checkout shows the Cargo version alone.
 Project-local tool installs belong under the gitignored `.work/` directory, for example
 `cargo install --root .work/tools ...`, so the global `~/.cargo/bin` stays untouched.
 
-## Nix development shell (optional)
-
-Install Nix with flakes enabled and run `nix develop` from the repository root. The
-committed `flake.lock` pins nixpkgs and rust-overlay; the shell reads the exact Rust
-version and components from `rust-toolchain.toml` and includes Python 3 and
-`cargo-machete`. On entry from the repository root it runs `cargo build --locked` and
-adds the checkout's `target/debug` to `PATH`, so `voltage --help` uses the development
-binary. Cargo's incremental build does not recompile unchanged sources. If the build
-fails, the shell remains available but does not add the binary to `PATH`. Once inside,
-run the [verification gate](#verification-gate) normally.
+## Kai development shell (optional)
+
+Install [Kai](https://github.com/thebrandonlucas/kai) (it needs Nix with flakes enabled)
+and run `kai shell` from the repository root. `Kaifile.roc` reads the exact Rust version
+and components from `rust-toolchain.toml` through rust-overlay, and adds Python 3 and
+`cargo-machete`. Run `kai update` to create `.kai/lock.json`, which pins the shell's
+sources; commit the lock file. Once inside, run the [verification gate](#verification-gate)
+normally.
 No OpenSSL or D-Bus development packages are required. Real Linux native keychain use
 still needs a running, unlocked Secret Service.
 
 For automatic activation, install direnv and enable its shell hook (for example,
-`eval "$(direnv hook zsh)"` in `.zshrc`, or use `bash` in `.bashrc`). Optionally install
-nix-direnv for cached activation, then run `direnv allow` in the repository root. Leave
-the directory to unload the shell. `.envrc` only activates the flake: it does not load
-`.env`, credentials, or staging endpoints.
-
-After editing Rust code in an already-open shell, run `cargo build --locked` to
-update the same `voltage` binary on `PATH` (or use `cargo run --locked -- ...` to
-build and run in one command). Direnv does not watch Rust source changes. After
-editing the shell, run `nix develop` again (or `direnv reload` if using direnv).
-To update the pinned sources deliberately, run `nix flake update`, review the
-`flake.lock` diff, rerun the full gate in `nix develop`, and commit the lock file.
-When changing Rust versions or components, update `rust-toolchain.toml` as well and
-verify `rustc --version` in the shell. Supported shell targets are aarch64/x86_64
-macOS and Linux; all four shell derivations evaluate, but only aarch64 macOS was built
-and tested with Nix. The other Nix shells remain unverified at runtime (CI builds those
-platforms using rustup). Native Windows Nix is not
-supported. This is a development environment, not a release artifact or a Nix package.
-
-Nix and direnv are not required: `rustup toolchain install` installs the pinned
+`eval "$(direnv hook zsh)"` in `.zshrc`, or use `bash` in `.bashrc`), then run
+`direnv allow` in the repository root. Leave the directory to unload the shell. `.envrc`
+only activates the Kai shell: it does not load `.env`, credentials, or staging endpoints.
+
+The shell does not build `voltage` or put `target/debug` on `PATH`; run
+`cargo build --locked` (or `cargo run --locked -- ...`) as usual. After editing
+`Kaifile.roc`, run `kai shell` again (or `direnv reload` if using direnv). To update the
+pinned sources deliberately, run `kai update`, review the `.kai/lock.json` diff, rerun the
+full gate in the shell, and commit the lock file. When changing Rust versions or
+components, update `rust-toolchain.toml` as well and verify `rustc --version` in the
+shell. Kai runs only on Linux (x86-64 and aarch64), so macOS and Windows developers use
+the rustup workflow below. The shell does not add `llvm-tools-preview`, which the
+[CRAP report](quality.md#crap-risk-check) needs. This is a development environment, not
+a release artifact or a Nix package.
+
+Kai, Nix, and direnv are not required: `rustup toolchain install` installs the pinned
 Rust toolchain, and `cargo install cargo-machete --version 0.9.2 --locked` supplies
 the extra verification tool for the existing rustup workflow.
 

docs/quality.md

@@ -193,8 +193,8 @@ KNOTS_BIN=.work/tools/bin/knots scripts/crap-report.sh
 ```
 
 `cargo-llvm-cov` also needs the `llvm-tools-preview` toolchain component. The
-`nix develop` shell includes it. With rustup, run
-`rustup component add llvm-tools-preview` once. CI does not install it.
+Kai shell does not include it. Run `rustup component add llvm-tools-preview` once. CI
+does not install it.
 
 The script builds an instrumented binary and runs the whole test suite, which
 takes several minutes, and writes `crap.md` and `crap.json` below