pond: Instructions file for Codex

Pond - project instructions

<comment_instructions>

1. Minimalism: Write comments only when the why of the code is not obvious from the code itself. Never explain the what.
2. Self-Documenting Code: Choose clear, descriptive names for variables, functions, and classes so that comments become redundant.
3. Banned Comments: DO NOT include:
   • Trivial explanations (e.g., # Loop through users).
   • "TODO" notes or author tags unless explicitly requested.
   • Autogenerated file headers or boilerplate comments.
4. Formatting: Place comments on the same line as simple logic or directly above complex blocks. Keep explanations strictly under two sentences. </comment_instructions>

Commands

• Build: cargo build
• Test: cargo test
• Lint: cargo clippy -- -D warnings
• Format: cargo fmt --check (use cargo fmt to fix)
• Lockfile is enforced in CI with --locked; locally, plain commands are fine. If Cargo.lock changes unexpectedly, git status will show it.

Toolchain

flake.nix is the single source of truth for the dev toolchain - rust (read from rust-toolchain.toml), moon and protoc (read from .prototools), zig, cargo-zigbuild, rcodesign, the macOS SDK stubs, uv, node/npm. gh is deliberately not in it: use the host's, so the host's GitHub auth wiring is never shadowed. In CI, pond-ci jobs get gh from the pond-runner image and GitHub-hosted runners ship their own. nix eval --json .#lib.toolVersions prints the pins, and the flake-check job asserts the table's text form matches what it evaluates to. The Linux CI legs enter this shell through .github/actions/devshell; the jobs without it (the two Windows legs, publish-release) read the same .prototools pins as text and download those releases directly, so a moon or protoc bump is the .prototools version plus that tool's archive hashes in flake.nix and an ops/toolchain-id.json regen. kache is not in the flake at all: it is a per-machine tool (its daemon and the global rustc-wrapper in ~/.cargo/config.toml belong to the machine, and a repo pin that differs from the daemon's version never shares cache entries with it), so developers install it themselves (mise use -g github:kunobi-ninja/kache@latest or brew install kunobi-ninja/kunobi/kache). CI pins it in two places, each a version plus sha256: the Windows legs in the anchored Start kache step, and dist-build-unix (the only Linux consumer) in its Install kache step, both in ci.yml, so a kache bump is both of those plus, when it changes cache keys, the k-tag in .github/kache/*.toml (windows-verify's pull_request_prefix included) and in dist-build-unix's KACHE_S3_PREFIX, together. The Windows legs run kache without kache-action, whose post step skips cancelled runs: their own Save kache step (if: always()) attempts to publish the prefetch manifest on cancel too. The Windows legs' kache remote is Cloudflare R2 (bucket pond-kache, secrets KACHE_R2_*): Hetzner rejects the quoted If-Match kache's manifest merges send, so prefetch went stale there. The Linux dist leg stays on Hetzner ttq, with prefetch off. node and npm are pinned twice, in toolVersions and .moon/toolchains.yml, until those go versionless. The flake-check parity step guards the .prototools and rust-toolchain.toml reads, not the kache or node/npm copies.