# nix-overlay — commands

All run from repo root (`nix-overlay/`).

## Build / run
- `nix build .#<package>` — build one package (must be `git add`-ed first if new; blueprint reads git index).
- `nix run .#<package>` — run a package CLI (needs `meta.mainProgram`).
- `nix build .#default` — build the meta-package (package listing).
- `nix flake show` — inspect flake outputs (also index-limited).
- `nix flake check` — full check incl. formatting.
- `nix develop` — dev shell from blueprint.

## Format
- `nix fmt` (treefmt → nixfmt on *.nix). Same as `nix flake check`'s format gate.

## Package updates
- `nix-update <package>` — bump version + hashes (cargoHash etc.).
- `nix-update <package> --version <v>` — specific version.
- `nix-update skillsmcp --version=branch=main` — for commit-pinned pkgs; or `--commit <sha>`.

## Beads (mandatory task tracking)
- `br robot-docs guide` — session context, run before any work.
- `br ready` / `br show <id>` / `br update <id> --claim` / `br close <id>`.
- `br update <id> --append-notes "..."` — persistent knowledge instead of MEMORY.md.
- `br sync --flush-only` — export issue state to `.beads/issues.jsonl`; runs no git commands.

## Session completion push
```
git pull --rebase && br sync --flush-only && git add .beads/ && git commit -m "sync beads" && git push
git status  # must show "up to date with origin"
```

## Serena
- `serena memories check` — verify memory references after edits/deletes.