docs: document the build + local-check workflow in conventions

Devshell-only builds (no global toolchain), nix fmt as the
authoritative formatter, and the full-flake-check gates the devshell
misses — notably the hivectl-docs regen after any hivectl verb/flag
change. Pulled out of the hive-wide knowledge repo, which keeps only
the portable kernel.

docs/conventions.md

@@ -406,6 +406,50 @@ Stage and commit when work *looks* ready, then run validation
 follow-up commit rather than an amend. The commit history is the
 work log; rewriting it loses signal.
 
+## Building & local checks
+
+Build through the **flake devshell**, not a bare toolchain — agent
+containers ship no global rust. `nix develop -c <cmd>` runs one
+command inside the project-pinned env (cargo/clippy/rustfmt plus the
+C compiler + `libsqlite3`/`ring` link deps); outside it a bare
+`cargo build` fails with `failed to find tool "cc"` / `cannot find
+-lsqlite3`. One command per invocation — agents run each task as a
+fresh non-interactive process, so there's no persistent shell to
+reuse.
+
+```sh
+nix develop -c cargo clippy --all-targets -- -D warnings
+nix develop -c cargo test
+nix fmt                       # treefmt — authoritative, NOT bare cargo fmt
+```
+
+`nix fmt` (treefmt) is the formatter CI gates on; bare `cargo fmt`
+misses the non-rust files treefmt also covers, so always run `nix
+fmt` before pushing.
+
+**The devshell checks are not the full `nix flake check`.** Clippy /
+fmt / `cargo test` cover most gates, but `nix flake check` runs extra
+check derivations they don't:
+
+- **`hivectl-docs`** regenerates `docs/tools/hivectl-cli.md` from
+  hivectl's clap tree and **fails if the committed copy is stale**.
+  So **after any change to a hivectl verb or flag, regenerate it**:
+  ```sh
+  nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md
+  ```
+  clippy / fmt / `cargo test` all pass *without* this — only the
+  flake check catches the drift, and `ci-log` often can't show you
+  why (it 500s on a fast failure), so you're left guessing "builder
+  flake" when it's a stale doc.
+- there's also a flake `cargo-test` check and NixOS module
+  evaluation in the set.
+
+When local clippy/fmt/test pass but CI's `nix flake check` fails,
+**don't assume a transient builder problem** — reproduce the real
+gate locally: `nix flake check` (shares the build farm, use
+sparingly) or build just the suspect check, e.g. `nix build
+.#checks.x86_64-linux.hivectl-docs`.
+
 ## Best-effort oneshot services
 
 The harness ships a family of one-shot systemd services that