For agents, on top of README.md, which they read first.

• The module only launches the sidecar CLI. What happens in the database is the CLI's (crates/postjevsql-sidecar). Never add SQL to the unit: that would be a second engine beside the one the container image and users' own Postgres call.
• The generated TOML is in the store, so it names secret FILES only: passwords as /run/credentials/postjevsql-sidecar.service/… paths (LoadCredential), the API key as apiKeyFile. Never interpolate a secret into it or a command line: both are world-readable (the store, /proc). The nixosTest greps for the password.
• sidecar-cli.nix reuses package.nix through passthru.buck; change the sandbox build there, once.
• package.nix parses third-party/BUCK's http_archive blocks at eval and throws on any other shape; if reindeer's output changes, fix the match, never hand-list crates. Adding a major means adding it to PG_MAJORS; the package builds it with --target-platforms //platforms:pgNN (third-party/pg_major.bzl sets pgrx's feature).
• package.nix's src is a fileset of what //crates/postjevsql:ext reads, docs excluded, so doc and test edits do not rebuild it. A new directory or root file the build reads must be added to that list, or buck fails in the sandbox with a missing path.
• Build through the flake (nix build .#), which passes the pinned buck2; nixpkgs' own buck2 has the h2 window bug (tests/CLAUDE.md).