[imattau]

Refs #18 (does not close it).

Publishing, forking, finding and consuming Nix build recipes as npack artifacts.

Changes

Protocol / core

• Optional release tag kind (e.g. nix-recipe). Non-package kinds are refused by install/update before downloading, and shown by resolve.
• Optional fork-of tag (publisher, name, release event ID): provenance only.
• npack resolve --release <event-id> pins one exact release with the usual signature/trust/revocation/name/os-arch checks.

Authoring and forking

• npack init --kind nix-recipe defaults os/arch to any and scaffolds a default.nix; --fork-of <publisher>/<name>@<id> records provenance.
• npack unpack <ref> --output DIR downloads, hash-verifies and extracts a package (also the way to review a recipe's code). With --fork-as <publisher> [--name N] it writes a manifest that inherits kind and records fork_of, so no extra flags are needed to fork.

Discovery

• npack search --kind <kind>; search and info show [kind] and (fork of ...).

Nix consumer (packaging/nix)

• lib.nix: fetchRecipe, fromPins, fromPinsWith { pinsFile, trustedPublishers } (evaluation fails for any other publisher). Recipes share one scope, so a declared dependency is a plain function argument.
• flake.nix (lib and overlay).
• npack-nix-pin: recursive pinning, a summary of new/changed pins, --check (exit 1 if pins would change), refusal to silently replace a pin with one from another publisher, and a warning when a dependency resolves to a different publisher than its dependent.

Docs: protocol (kind, fork-of), a full publish/fork/use workflow in using-npack.md with a NixOS example and trust notes, and CLAUDE.md.

Agent guide: a canonical AGENTS.md (architecture, release/install flow, code map, how to test end to end with a local relay, gotchas; not Nix-specific). CLAUDE.md now just imports it.

Verified

• cargo fmt --check, cargo clippy --all-targets, cargo test pass (72 + 3).
• End to end against a local relay + Blossom (nak serve --blossom), building in a Debian VM with Nix: resolve, resolve --release, search --kind, info, unpack --fork-as then repack and publish of a fork, npack-nix-pin (including --check and the conflict refusal), a recipe with a dependency, and the flake. trustedPublishers rejects an unlisted publisher. A tampered hash is rejected.
• Finding: a dependency declared without a publisher resolves to whichever publisher has a package of that name (existing npack behaviour). Documented; recipes should declare the dependency's publisher.

Not done

• Not tested on real NixOS or public relays, or with the issue reporter's recipes.
• Evaluation uses import-from-derivation, so it is not suitable for nixpkgs/Hydra.
• The pin tool is a Python script and the Nix files are not shipped in release artifacts; they are consumed via the flake input or copied.
• Pins carry mirror URLs as published; refresh by rerunning npack-nix-pin.
• Binary-cache linkage is out of scope.

🤖 Generated with Claude Code