docs: note that linking workspace binaries locally needs nix develop (libsqlite3)

docs/gotchas.md

@@ -209,6 +209,28 @@ and fail outright if the host daemon's
 fall back to unsandboxed local builds rather than failing. Security
 implications: `docs/security.md`.
 
+## Linking workspace binaries locally needs `nix develop`
+
+The Rust workspace links `libsqlite3-sys` (rusqlite) against the
+system `libsqlite3`. Agent containers carry no system libsqlite3 on
+the linker path, so a plain `cargo build` of any binary dies with
+`cannot find -lsqlite3` (deps and `ring` compile fine — only the
+final link fails). `cargo check` / `cargo clippy` still work in the
+ambient shell since they never link.
+
+Build + run binaries through the dev shell, which carries `sqlite`
+on `NIX_LDFLAGS`:
+
+```bash
+nix develop -c cargo build -p hive-c0re --bin hivectl
+nix develop -c cargo run -p hive-c0re --bin hivectl -- <args>
+```
+
+This is also how you regenerate committed generated docs locally —
+e.g. `docs/tools/hivectl-cli.md` via the `hivectl markdown-docs`
+subcommand (its `hivectl-docs` flake check otherwise only fails in
+CI on drift).
+
 ## Split asset derivations away from the rust workspace
 
 `nix/assets.nix` builds the branding SVG/PNG family + claude