docs/nixpkgs: Expand upgrade workflow

Move the skill to the shared agent location while retaining Claude
compatibility. Document kernel refreshes and the release metadata
policy as part of each upgrade, and make commit-message wrapping
explicit and verifiable.

.agents/skills/upgrade-nixpkgs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: upgrade-nixpkgs
+description: >-
+  Upgrade all four nixpkgs channels (unstable, stable, mine, mine-stable) and home-manager for this
+  flake: check for a NixOS stable bump, rebase the devplayer0 nixpkgs fork, update kernel and
+  release metadata, refresh pins, sweep version-gated TODOs, and review other inputs. Use when the
+  user wants to update/bump nixpkgs, refresh the pins, or do the periodic nixpkgs/home-manager
+  upgrade.
+---
+
+# Upgrade nixpkgs
+
+Read [`docs/nixpkgs-upgrade.md`](../../../docs/nixpkgs-upgrade.md), the canonical procedure, and
+follow its phases in order.
+
+Key reminders (see the doc for the full steps):
+
+- It is **guided, not automated** — do the mechanical and investigative work but stop at the ⏸
+  points: pushing the fork, resolving rebase conflicts, applying a stable-channel bump, choosing a
+  new release codename, and deleting version guards. Report the findings and let the user decide.
+- **Check the current NixOS stable first** (Phase 1) — the fork's `devplayer0-stable` rebase target
+  and the `flake.nix` stable pins must agree on one release.
+- **Re-verify the patch stack against freshly fetched upstream**, not stale refs — enumerate it with
+  `git log`; don't assume a remembered list.
+- After refreshing the pins, update `lib/constants.nix` to the current explicit LTS and latest
+  kernel package attributes, and update the `lib/default.nix` version overlay's `YY.MM` prefix to
+  the current month. Change its codename only when the stable channel advances.

.claude/skills/upgrade-nixpkgs

@@ -0,0 +1 @@
+../../.agents/skills/upgrade-nixpkgs

.claude/skills/upgrade-nixpkgs/SKILL.md

@@ -1,25 +0,0 @@
----
-name: upgrade-nixpkgs
-description: >-
-  Upgrade all four nixpkgs channels (unstable, stable, mine, mine-stable) and home-manager for this
-  flake: check for a NixOS stable bump, rebase the devplayer0 nixpkgs fork against upstream, run the
-  update commands, sweep version-gated TODOs, and review flake inputs. Use when the user wants to
-  update/bump nixpkgs, refresh the pins, or do the periodic nixpkgs/home-manager upgrade.
----
-
-# Upgrade nixpkgs
-
-The canonical, agent-agnostic procedure lives in the repo at
-[`docs/nixpkgs-upgrade.md`](../../../docs/nixpkgs-upgrade.md). Read it and follow the phases in
-order.
-
-Key reminders (see the doc for the full steps):
-
-- It is **guided, not automated** — do the mechanical/investigative work but stop at the ⏸ points:
-  pushing the fork, resolving rebase conflicts, editing the `flake.nix` stable pins, and deleting
-  version guards. Report and let the user decide.
-- **Check the current NixOS stable first** (Phase 1) — the fork's `devplayer0-stable` rebase target
-  and the `flake.nix` stable pins must agree on one release.
-- **Re-verify the patch stack against freshly fetched upstream**, not stale refs — enumerate it with
-  `git log`, don't assume a remembered list (stale `upstream/*` refs make already-upstreamed commits
-  masquerade as fork-only patches).

AGENTS.md

@@ -65,8 +65,9 @@ Common ones:
   `$INSTALLER`. For bringing up a new box end to end follow the guided procedure in
   [`docs/install-box.md`](docs/install-box.md).
 - `update-nixpkgs` / `update-home-manager` — bump pinned inputs. For the full periodic upgrade
-  (rebasing the `devplayer0` nixpkgs fork, stable-release bumps, version-gate sweep, input review)
+  (rebasing the `devplayer0` nixpkgs fork, stable-release bumps, kernel and release-metadata
-  follow the guided procedure in [`docs/nixpkgs-upgrade.md`](docs/nixpkgs-upgrade.md).
+  refreshes, version-gate sweep, input review) follow the guided procedure in
+  [`docs/nixpkgs-upgrade.md`](docs/nixpkgs-upgrade.md).
 
 Use the narrowest relevant evaluation while iterating: `check-system <host>` for a box config,
 `nix eval .#nixfiles.config.nixos.allAssignments --json` for assignment generation, or
@@ -211,10 +212,13 @@ in churn.
   command, option or upstream technical term such as QEMU's machine type.
 - Commit subjects follow `area/scope: Capitalized summary` (e.g. `nixos/home: ...`); keep logically
   distinct changes in separate commits. Aim for 50-character subjects and do not exceed 72
-  characters. Wrap commit bodies at 72 columns. A concise body describing the change and its
+  characters. Hard-wrap commit body lines at 72 characters; Git preserves an unwrapped `-m`
-  rationale is welcome when the subject alone does not provide enough context — keep it to the
+  argument as one long line, so include literal line breaks or use a commit-message file. Before
-  essentials rather than restating the diff. `Co-Authored-By` is the only trailer used here; do
+  reporting a commit, inspect `git show -s --format=%B HEAD` and amend it if any line exceeds 72
-  **not** add a `Claude-Session` link (or any other session/tooling trailer).
+  characters. A concise body describing the change and its rationale is welcome when the subject
+  alone does not provide enough context — keep it to the essentials rather than restating the diff.
+  `Co-Authored-By` is the only trailer used here; do **not** add a `Claude-Session` link (or any
+  other session/tooling trailer).
 - **"Logically distinct" means unrelated** — two different applications, two boxes that have nothing
   to do with each other, a drive-by fix that happens to sit in a file you were editing anyway. One
   piece of work stays in one commit even when it touches a config, several docs and a switch: if the

docs/nixpkgs-upgrade.md

@@ -2,13 +2,14 @@
 
 Procedure for the periodic upgrade of all four nixpkgs channels (`unstable`, `stable`, `mine`,
 `mine-stable`) and home-manager. Written to be followed by a person or any coding agent; a
-Claude Code entry point exists at `.claude/skills/upgrade-nixpkgs/` but the steps below are the
+shared agent-skill entry point exists at `.agents/skills/upgrade-nixpkgs/`, but the steps below are
-canonical source.
+the canonical source.
 
 The upgrade is **guided, not automated**: do the mechanical and investigative steps, but stop at
 the judgment points (marked ⏸) — pushing the fork, resolving rebase conflicts, editing the
-`flake.nix` stable pins, and deleting version guards. Report findings and let the maintainer
+stable-channel configuration, choosing a new release codename, and deleting version guards. Report
-decide. Keep a running summary and present it before any push or commit.
+findings and let the maintainer decide. Keep a running summary and present it before any push or
+commit.
 
 Work the phases in order; skip one only if explicitly scoped to a subset.
 
@@ -43,6 +44,7 @@ stable pins) has to agree on one NixOS stable release, so establish it up front.
    the pieces must all move to the same release together:
    - Rebase `devplayer0-stable` onto the new `upstream/release-YY.NN` (Phase 2 uses this target).
    - Edit `flake.nix`: `nixpkgs-stable.url` and `home-manager-stable.url` → the new release.
+   - Choose a new `lib/default.nix` `versionOverlay` codename (Phase 4 updates it).
    - Bump each system's `stateVersion` / `home.stateVersion` only if the maintainer explicitly
      wants to — that is a separate, deliberate decision; never auto-bump.
    Don't edit `flake.nix` here without confirmation.
@@ -83,7 +85,28 @@ update-home-manager
 Then show the `flake.lock` diff for the nixpkgs/home-manager entries so the old→new revisions are
 visible.
 
-## Phase 4 — Sweep version-gated behavior
+## Phase 4 — Refresh kernels and release metadata
+
+Update the repository values that deliberately move with nixpkgs upgrades:
+
+1. In `lib/constants.nix`, inspect the kernel attributes available from the refreshed nixpkgs pins
+   and update both explicit selections:
+   - `kernel.lts` → the newest upstream long-term-support kernel carried by nixpkgs.
+   - `kernel.latest` → the newest kernel series carried by nixpkgs.
+   Keep explicit `pkgs.linuxKernel.packages.linux_X_Y` attributes rather than replacing them with
+   moving aliases. Confirm both attributes exist in the unstable and stable package sets used by
+   the boxes; if the newest choice is unavailable on stable, report that instead of breaking the
+   shared constant.
+2. In `lib/default.nix`, update the `versionOverlay` values:
+   - Set the leading `YY.MM` in `trivial.release` to the current year and month. Preserve the
+     `:u-${prev.trivial.release}` suffix.
+   - If Phase 1 found a new NixOS stable release, ⏸ ask the maintainer to choose or approve a new
+     `trivial.codeName`, then update it as part of the coordinated stable bump. Otherwise retain the
+     existing codename.
+
+Show these edits alongside the input changes in the upgrade summary.
+
+## Phase 5 — Sweep version-gated behavior
 
 The repo carries branch-conditional logic and TODOs keyed to specific nixpkgs versions; some become
 removable after an upgrade, especially after a stable bump. Surface them:
@@ -97,7 +120,7 @@ Known example: `nixos/modules/common.nix` carries a `# TODO: Remove if-else when
 guard. For each hit, evaluate whether the now-current versions make the guard removable and list
 candidates. ⏸ Don't delete guards without confirmation — some protect the still-supported stable.
 
-## Phase 5 — Review remaining flake inputs
+## Phase 6 — Review remaining flake inputs
 
 Don't blanket-update. Walk the other inputs deliberately:
 
@@ -109,17 +132,17 @@ Don't blanket-update. Walk the other inputs deliberately:
 3. Propose a per-input update list with reasons; update the approved ones with targeted
    `nix flake update <input>`, not a global update.
 
-## Phase 6 — Validate
+## Phase 7 — Validate
 
 1. `nix flake check --no-build` (broad eval; reproduces CI's cheap checks).
 2. `check-system <host>` on a representative box, and one exercising the stable channel if the
-   boxes mix channels.
+   boxes mix channels. This must exercise the refreshed kernel constants on both channels.
 3. Report eval/build results honestly. On failure, surface the error and stop rather than papering
    over it.
 
 ## Wrap-up
 
 Present a final summary: fork rebase outcome (patches kept/dropped/conflicted), whether a stable
-bump is pending or was applied, the lock diff, version-gate cleanup candidates, inputs updated, and
+bump is pending or was applied, kernel and release-metadata changes, the lock diff, version-gate
-validation results. Leave committing to the maintainer unless asked; if committing, follow the
+cleanup candidates, inputs updated, and validation results. Leave committing to the maintainer
-repo's `area/scope: Capitalized summary` convention.
+unless asked; if committing, follow the repo's `area/scope: Capitalized summary` convention.