diff --git a/.agents/skills/cachix/SKILL.md b/.agents/skills/cachix/SKILL.md new file mode 100644 index 0000000..99f8b21 --- /dev/null +++ b/.agents/skills/cachix/SKILL.md @@ -0,0 +1,84 @@ +--- +name: cachix +description: | + Use this skill when working on this repo's Cachix cache, Nix/devenv closure, + or Tangled CI speed. Triggers: Cachix, binary cache, rssbase cache, + CACHIX_AUTH_TOKEN, pushing Nix store paths, speeding up devenv in CI, + or changes to devenv.nix, devenv.lock, devenv.yaml, devenv.custom-code.nix, + tangled-cli/tang.nix, or other Nix package definitions. +--- + +# cachix — rssbase binary cache workflow + +This repo uses the `rssbase` Cachix cache to speed up Nix/devenv materialization. +The cache is consumed by `devenv.nix` via: + +```nix +cachix.pull = [ "rssbase" ]; +``` + +## Token handling + +Never commit Cachix tokens. Store a write token as a Tangled repository secret or +provide it only in the process environment: + +```bash +export CACHIX_AUTH_TOKEN=... +``` + +If a token was pasted in chat or logs, recommend rotating it in Cachix and storing +the replacement as a secret named `CACHIX_AUTH_TOKEN`. + +## When to push to Cachix + +Push to Cachix after changes that alter the devenv/Nix closure, especially: + +- `devenv.nix`, `devenv.lock`, `devenv.yaml` +- `devenv.custom-code.nix` +- files under `tangled-cli/` such as `tangled-cli/tang.nix` +- adding/removing/upgrading Nix packages or devenv modules +- before benchmarking Tangled CI speed for a new Nix/devenv setup + +Do not bother pushing for changes that do not affect the Nix closure, such as: + +- application-only code/docs changes +- `.tangled/workflows/*.yml` changes that only edit commands/triggers +- README/AGENTS/skill text changes + +## Push workflow + +First materialize the current devenv locally: + +```bash +devenv shell echo hello +``` + +Then push the current top-level devenv outputs and their runtime closures: + +```bash +paths=() +for p in \ + .devenv/gc/shell \ + .devenv/profile \ + .devenv/gc/task-config-devenv-config-task-config \ + .devenv/gc/test-devenv-config-test \ + .devenv/gc/changelog-json-devenv-config-changelog-json + do + [ -e "$p" ] && paths+=("$(readlink -f "$p")") +done + +cachix push rssbase "${paths[@]}" +``` + +If `cachix` is not directly available and `DEVENV_ROOT` is not active, run it +through devenv: + +```bash +devenv shell cachix push rssbase "${paths[@]}" +``` + +## Verify + +After pushing, trigger or force-push a Tangled pipeline and compare the runtime. +If the workflow still spends most of its time in microVM boot, clone, or devenv +evaluation, extra Cachix pushes may not improve the wall-clock time.