fix(nixpkgs): rename apfel-ai -> apfel-llm everywhere (#137)

Upstream NixOS/nixpkgs landed the package as apfel-llm via PR #508084
(merged 2026-04-22), not apfel-ai. Our auto-bump workflow was opening
PRs against pkgs/by-name/ap/apfel-ai/package.nix - a path that no
longer exists - so every release since 1.0.5 has had its nixpkgs bump
quietly fail. A community contributor (arunoruto) has been bumping
versions manually upstream.

Renames apfel-ai -> apfel-llm across:
- .github/workflows/bump-nixpkgs.yml (workflow name, file path, branch
  name, commit message, PR title)
- scripts/bump-nixpkgs.sh (comment header)
- Tests/integration/test_nixpkgs_bump.py (pname fixture)
- docs/install.md (Option 2 nix install: now shipped, not pending)
- docs/nixpkgs.md (every reference + rewritten "Why" section noting
  upstream chose -llm over our original -ai proposal)
- docs/release.md (distribution channels table)
- docs/routines.md (one prose mention)
- .claude/routines/04-dist-channel-watch.md (channel-sync routine)
- CLAUDE.md (distribution list + nixpkgs channel description)
- README.md (Nix added to install.md pointer)

Closes #137.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Arthur-Ficial

.claude/routines/04-dist-channel-watch.md

@@ -22,7 +22,7 @@ Check whether apfel's three distribution channels are in sync. If any channel is
 |---|---|
 | **GitHub Releases** (the upstream that the other two feed from) | `gh release view --repo Arthur-Ficial/apfel` latest tag, published-at |
 | **homebrew-core** (`brew install apfel`) | `curl -s https://raw.githubusercontent.com/Homebrew/homebrew-core/master/Formula/a/apfel.rb` - look for the `version` / `url` fields |
-| **nixpkgs** (`nix profile install nixpkgs#apfel-ai`) | `curl -s https://raw.githubusercontent.com/NixOS/nixpkgs/master/pkgs/by-name/ap/apfel-ai/package.nix` - look for the `version` field |
+| **nixpkgs** (`nix profile install nixpkgs#apfel-llm`) | `curl -s https://raw.githubusercontent.com/NixOS/nixpkgs/master/pkgs/by-name/ap/apfel-llm/package.nix` - look for the `version` field |
 
 ### Step-by-step
 
@@ -40,7 +40,7 @@ Check whether apfel's three distribution channels are in sync. If any channel is
 
 4. **Fetch the nixpkgs package** and parse its version:
    ```bash
-   curl -sf https://raw.githubusercontent.com/NixOS/nixpkgs/master/pkgs/by-name/ap/apfel-ai/package.nix | grep -E 'version|hash'
+   curl -sf https://raw.githubusercontent.com/NixOS/nixpkgs/master/pkgs/by-name/ap/apfel-llm/package.nix | grep -E 'version|hash'
    ```
 
 5. **Compute lag.** For each channel that is behind the latest GitHub Release:
@@ -68,7 +68,7 @@ Routine check this morning - looks like <channel(s)> are trailing the latest rel
 |---|---|---|---|
 | GitHub Releases | v<canonical> | - | - |
 | homebrew-core | v<hb-current> | v<canonical> | ~<N>h |
-| nixpkgs `apfel-ai` | <nix-current> | <canonical> | ~<N>h |
+| nixpkgs `apfel-llm` | <nix-current> | <canonical> | ~<N>h |
 
 ## Fixing it (for you, not me)
 
@@ -91,7 +91,7 @@ gh workflow run bump-nixpkgs.yml --repo Arthur-Ficial/apfel -f version=<canonica
 Or from a local nixpkgs checkout:
 
 \```bash
-./scripts/bump-nixpkgs.sh --version <canonical> --file pkgs/by-name/ap/apfel-ai/package.nix
+./scripts/bump-nixpkgs.sh --version <canonical> --file pkgs/by-name/ap/apfel-llm/package.nix
 \```
 
 ## What I did NOT do

.github/workflows/bump-nixpkgs.yml

@@ -1,8 +1,8 @@
-name: Bump nixpkgs apfel-ai
+name: Bump nixpkgs apfel-llm
 
 # Fires when `make release` publishes a new GitHub Release. The workflow
 # forks/pulls NixOS/nixpkgs, runs scripts/bump-nixpkgs.sh to update
-# version + hash in pkgs/by-name/ap/apfel-ai/package.nix, and opens a
+# version + hash in pkgs/by-name/ap/apfel-llm/package.nix, and opens a
 # bump PR against nixpkgs master.
 #
 # This is our Layer 2 fallback -- the community r-ryantm bot usually
@@ -78,9 +78,9 @@ jobs:
         run: |
           bash ./scripts/bump-nixpkgs.sh \
             --version "$VERSION" \
-            --file "nixpkgs/pkgs/by-name/ap/apfel-ai/package.nix"
+            --file "nixpkgs/pkgs/by-name/ap/apfel-llm/package.nix"
           # If git status shows no change, we're idempotent - bail early.
-          if git -C nixpkgs diff --quiet -- pkgs/by-name/ap/apfel-ai/package.nix; then
+          if git -C nixpkgs diff --quiet -- pkgs/by-name/ap/apfel-llm/package.nix; then
             echo "changed=0" >> "$GITHUB_OUTPUT"
           else
             echo "changed=1" >> "$GITHUB_OUTPUT"
@@ -96,10 +96,10 @@ jobs:
         run: |
           git config user.name "Arthur Ficial"
           git config user.email "arti.ficial@fullstackoptimization.com"
-          branch="apfel-ai-$VERSION"
+          branch="apfel-llm-$VERSION"
           git checkout -b "$branch"
-          git add pkgs/by-name/ap/apfel-ai/package.nix
-          git commit -m "apfel-ai: $VERSION"
+          git add pkgs/by-name/ap/apfel-llm/package.nix
+          git commit -m "apfel-llm: $VERSION"
           git push --force origin "$branch"
           echo "branch=$branch" >> "$GITHUB_OUTPUT"
 
@@ -137,6 +137,6 @@ jobs:
             gh pr create --repo NixOS/nixpkgs \
               --head "Arthur-Ficial:$BRANCH" \
               --base master \
-              --title "apfel-ai: $VERSION" \
+              --title "apfel-llm: $VERSION" \
               --body "$body"
           fi

CLAUDE.md

@@ -86,7 +86,7 @@ HTTP Server (/v1/*) ───────┘   ContextManager → Transcript API
 
 - Version: `1.0.0` (source of truth: `.version`)
 - Tests: 366 unit + 220 integration
-- Distribution: homebrew-core (`brew install apfel`), nixpkgs (`nix profile install nixpkgs#apfel-ai`), and the Arthur-Ficial/homebrew-tap
+- Distribution: homebrew-core (`brew install apfel`), nixpkgs (`nix profile install nixpkgs#apfel-llm`), and the Arthur-Ficial/homebrew-tap
 - Stability policy: [STABILITY.md](STABILITY.md)
 - Security policy: [SECURITY.md](SECURITY.md)
 
@@ -328,7 +328,7 @@ apfel ships through three channels. All pull the same signed tarball from each G
 
 - **homebrew-core** - `brew install apfel`. Autobump detects new releases; latency ~24h. We do not maintain the formula.
 - **Arthur-Ficial/homebrew-tap** - `brew install Arthur-Ficial/tap/apfel`. Synchronous, pushed as part of `make release`. Secondary channel; also houses apfel-family tools (apfel-chat, apfel-clip, apfel-mcp, etc.).
-- **nixpkgs** - `nix profile install nixpkgs#apfel-ai`. Name is `apfel-ai` because nixpkgs already has an unrelated physics `apfel`. Two-layer automation: community r-ryantm bot (~weekly) plus our `.github/workflows/bump-nixpkgs.yml` on every release (~5 min). See [docs/nixpkgs.md](docs/nixpkgs.md). Requires the `NIXPKGS_BUMP_PAT` repo secret.
+- **nixpkgs** - `nix profile install nixpkgs#apfel-llm`. Name is `apfel-llm` because nixpkgs already has an unrelated physics `apfel` package and the disambiguator landed upstream as `apfel-llm` (PR NixOS/nixpkgs#508084). Two-layer automation: community r-ryantm bot (~weekly) plus our `.github/workflows/bump-nixpkgs.yml` on every release (~5 min). See [docs/nixpkgs.md](docs/nixpkgs.md). Requires the `NIXPKGS_BUMP_PAT` repo secret.
 - Emergency Homebrew bump: `brew bump-formula-pr apfel --url=<tarball-url> --sha256=<hash>`
 - Emergency nixpkgs bump: run `scripts/bump-nixpkgs.sh` against a local nixpkgs clone and open a PR manually.
 

README.md

@@ -44,7 +44,7 @@ Build from source (Command Line Tools with macOS 26.4 SDK / Swift 6.3, no Xcode)
 git clone https://github.com/Arthur-Ficial/apfel.git && cd apfel && make install
 ```
 
-Same-day tap, Mint, mise, troubleshooting: [docs/install.md](docs/install.md).
+Nix, same-day tap, Mint, mise, troubleshooting: [docs/install.md](docs/install.md).
 
 ## Quick Start
 

Tests/integration/test_nixpkgs_bump.py

@@ -28,7 +28,7 @@
 }}:
 
 stdenvNoCC.mkDerivation (finalAttrs: {{
-  pname = "apfel-ai";
+  pname = "apfel-llm";
   version = "{version}";
 
   src = fetchurl {{

docs/install.md

@@ -22,15 +22,13 @@ brew install Arthur-Ficial/tap/apfel
 
 No build tools needed. See [brew-install.md](brew-install.md) for troubleshooting.
 
-## Option 2: Nix (nixpkgs) - pending
-
-The initial nixpkgs submission ([NixOS/nixpkgs#510089](https://github.com/NixOS/nixpkgs/pull/510089)) is under upstream review and not yet merged. Once it lands:
+## Option 2: Nix (nixpkgs)
 
 ```bash
-nix profile install nixpkgs#apfel-ai
+nix profile install nixpkgs#apfel-llm
 ```
 
-Attribute name is `apfel-ai` because nixpkgs already has an unrelated `apfel` package (a particle-physics PDF library); the binary on `$PATH` is still `apfel`. See [docs/nixpkgs.md](nixpkgs.md) for automation details and tracking issue [#88](https://github.com/Arthur-Ficial/apfel/issues/88) for current status.
+Attribute name is `apfel-llm` because nixpkgs already has an unrelated `apfel` package (a particle-physics PDF library); the binary on `$PATH` is still `apfel`. The package landed via [NixOS/nixpkgs#508084](https://github.com/NixOS/nixpkgs/pull/508084). See [docs/nixpkgs.md](nixpkgs.md) for automation details.
 
 ## Option 3: Build from source
 

docs/nixpkgs.md

@@ -1,20 +1,22 @@
 # nixpkgs distribution
 
-apfel ships on [nixpkgs](https://github.com/NixOS/nixpkgs) under the attribute `apfel-ai`. This page explains the name choice, how the automation works, and how to test or repair the package locally.
+apfel ships on [nixpkgs](https://github.com/NixOS/nixpkgs) under the attribute `apfel-llm`. This page explains the name choice, how the automation works, and how to test or repair the package locally.
 
 ## Install (end users)
 
 ```bash
-nix profile install nixpkgs#apfel-ai
+nix profile install nixpkgs#apfel-llm
 ```
 
 Runtime requirements are the same as Homebrew: macOS 26 Tahoe or later, Apple Silicon, Apple Intelligence enabled, Siri language matching device language.
 
-The binary on your `$PATH` is still `apfel` - only the install-time attribute is `apfel-ai`.
+The binary on your `$PATH` is still `apfel` - only the install-time attribute is `apfel-llm`.
 
-## Why `apfel-ai` and not `apfel`
+## Why `apfel-llm` and not `apfel`
 
-nixpkgs already has an unrelated package at [`pkgs/by-name/ap/apfel`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/ap/apfel/package.nix): the [scarrazza/apfel](https://github.com/scarrazza/apfel) particle-physics PDF Evolution Library (GPL3, maintained by `veprbl`). The name was taken years before apfel-ai existed, so nixpkgs convention requires disambiguation.
+nixpkgs already has an unrelated package at [`pkgs/by-name/ap/apfel`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/ap/apfel/package.nix): the [scarrazza/apfel](https://github.com/scarrazza/apfel) particle-physics PDF Evolution Library (GPL3, maintained by `veprbl`). The name was taken years before apfel existed in its AI form, so nixpkgs convention requires disambiguation.
+
+The disambiguator that landed upstream is `apfel-llm` (via [NixOS/nixpkgs#508084](https://github.com/NixOS/nixpkgs/pull/508084)). An earlier proposal used `apfel-ai`, but the upstream maintainer chose `-llm` as the more descriptive suffix. The binary on `$PATH` is still `apfel` either way - only the install attribute differs.
 
 ## Why a pre-built binary derivation
 
@@ -39,8 +41,8 @@ Expected latency: within ~7 days of release.
 [`.github/workflows/bump-nixpkgs.yml`](../.github/workflows/bump-nixpkgs.yml) fires on every `release: published` event from `make release`. It:
 
 1. Checks out a fresh copy of `Arthur-Ficial/nixpkgs` (our fork, synced with upstream master).
-2. Runs [`scripts/bump-nixpkgs.sh`](../scripts/bump-nixpkgs.sh) to rewrite `version` and `hash` in `pkgs/by-name/ap/apfel-ai/package.nix`.
-3. Commits on a branch `apfel-ai-<version>`, force-pushes to the fork.
+2. Runs [`scripts/bump-nixpkgs.sh`](../scripts/bump-nixpkgs.sh) to rewrite `version` and `hash` in `pkgs/by-name/ap/apfel-llm/package.nix`.
+3. Commits on a branch `apfel-llm-<version>`, force-pushes to the fork.
 4. Opens a PR on `NixOS/nixpkgs` (or updates the existing one if already open).
 
 Expected latency: within ~5 minutes of release.
@@ -83,19 +85,19 @@ On any Mac with Nix installed (we use the Determinate Systems installer on Apple
 ```bash
 git clone --depth 1 https://github.com/NixOS/nixpkgs.git /tmp/nixpkgs-test
 cd /tmp/nixpkgs-test
-nix-build -A apfel-ai --no-out-link
+nix-build -A apfel-llm --no-out-link
 
 # The resulting binary:
-ls /nix/store/*-apfel-ai-*/bin/apfel
+ls /nix/store/*-apfel-llm-*/bin/apfel
 ```
 
-Run it: `/nix/store/...-apfel-ai-.../bin/apfel --version`.
+Run it: `/nix/store/...-apfel-llm-.../bin/apfel --version`.
 
 To test a version bump before pushing, point `--file` at your local checkout:
 
 ```bash
 ./scripts/bump-nixpkgs.sh --version 1.2.3 \
-  --file /tmp/nixpkgs-test/pkgs/by-name/ap/apfel-ai/package.nix \
+  --file /tmp/nixpkgs-test/pkgs/by-name/ap/apfel-llm/package.nix \
   --dry-run
 ```
 
@@ -105,21 +107,21 @@ Very rare, but: if r-ryantm is down and the workflow is broken, you can bump by
 
 ```bash
 cd /tmp/nixpkgs-test
-git fetch origin master && git checkout -B apfel-ai-manual origin/master
+git fetch origin master && git checkout -B apfel-llm-manual origin/master
 
 /path/to/apfel/scripts/bump-nixpkgs.sh \
   --version 1.2.3 \
-  --file pkgs/by-name/ap/apfel-ai/package.nix
+  --file pkgs/by-name/ap/apfel-llm/package.nix
 
-git add pkgs/by-name/ap/apfel-ai/package.nix
-git commit -m "apfel-ai: 1.2.3"
-git push fork apfel-ai-manual   # where `fork` is Arthur-Ficial/nixpkgs
-gh pr create --repo NixOS/nixpkgs --head Arthur-Ficial:apfel-ai-manual --base master \
-  --title "apfel-ai: 1.2.3"
+git add pkgs/by-name/ap/apfel-llm/package.nix
+git commit -m "apfel-llm: 1.2.3"
+git push fork apfel-llm-manual   # where `fork` is Arthur-Ficial/nixpkgs
+gh pr create --repo NixOS/nixpkgs --head Arthur-Ficial:apfel-llm-manual --base master \
+  --title "apfel-llm: 1.2.3"
 ```
 
 ## Tracking
 
-- Package source: <https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/ap/apfel-ai/package.nix>
-- nixpkgs PRs: <https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+apfel-ai>
-- r-ryantm PRs for apfel-ai: <https://github.com/NixOS/nixpkgs/pulls/r-ryantm?q=apfel-ai>
+- Package source: <https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/ap/apfel-llm/package.nix>
+- nixpkgs PRs: <https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+apfel-llm>
+- r-ryantm PRs for apfel-llm: <https://github.com/NixOS/nixpkgs/pulls/r-ryantm?q=apfel-llm>

docs/release.md

@@ -116,7 +116,7 @@ Each release is published through three channels. All three pull the same signed
 |---------|-----------|-----------|
 | [homebrew-core](https://github.com/Homebrew/homebrew-core/blob/master/Formula/a/apfel.rb) (`brew install apfel`) | Up to ~24h after release | Homebrew `autobump-PR` bot detects new GitHub Releases and opens a formula-bump PR. |
 | [Arthur-Ficial/homebrew-tap](https://github.com/Arthur-Ficial/homebrew-tap) (`brew install Arthur-Ficial/tap/apfel`) | Synchronous with release | `scripts/publish-release.sh` pushes the new formula directly as part of `make release`. |
-| [nixpkgs](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/ap/apfel-ai) (`nix profile install nixpkgs#apfel-ai`) | Within ~5 min of release (Layer 2), or ~weekly (Layer 1) | Two layers: community [`r-ryantm`](https://github.com/ryantm/nixpkgs-update) bot (primary, ~weekly), plus our own [`bump-nixpkgs.yml`](.github/workflows/bump-nixpkgs.yml) workflow that opens a PR on every `release: published` event (fallback, minutes). See [nixpkgs.md](nixpkgs.md). |
+| [nixpkgs](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/ap/apfel-llm) (`nix profile install nixpkgs#apfel-llm`) | Within ~5 min of release (Layer 2), or ~weekly (Layer 1) | Two layers: community [`r-ryantm`](https://github.com/ryantm/nixpkgs-update) bot (primary, ~weekly), plus our own [`bump-nixpkgs.yml`](.github/workflows/bump-nixpkgs.yml) workflow that opens a PR on every `release: published` event (fallback, minutes). See [nixpkgs.md](nixpkgs.md). |
 
 All three channels are "owned" in the sense that we file PRs against them and respond to reviewer feedback - but merges into homebrew-core and nixpkgs are gated by their respective maintainer communities. The tap is the only channel where we merge directly.
 

docs/routines.md

@@ -20,7 +20,7 @@ Routines run on Anthropic's Linux cloud runners, so they cannot:
 - Run `make test`, `make preflight`, `swift build`, or any integration test that needs Apple Intelligence (there is no Apple Intelligence on Linux)
 - Test the actual behavior of code changes - only static review (style, structure, test coverage, security audit)
 - Merge a PR, approve a PR, cut a release, or update any distribution channel (Homebrew, nixpkgs, tap)
-- Change what you install via `brew install apfel` or `nix profile install nixpkgs#apfel-ai`
+- Change what you install via `brew install apfel` or `nix profile install nixpkgs#apfel-llm`
 
 Every code-PR review from a routine contains an explicit note that functional correctness was **not** verified and that @franzenzenhofer needs to run tests locally before merging.
 

scripts/bump-nixpkgs.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# bump-nixpkgs.sh - update apfel-ai/package.nix version and hash.
+# bump-nixpkgs.sh - update apfel-llm/package.nix version and hash.
 #
 # Does NOT touch git or gh; callers (GitHub Actions workflow, humans)
 # drive commit/push/PR separately. This keeps the script deterministic