clean tests run: pi 1.5.0 model-list shim, panes checked by process, board r refreshes detail, office . accepted

.pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md

@@ -1599,3 +1599,44 @@ Troubleshooting: if address present but no route, `ip route add default via 192.
 - session: [[packs/paperclip-harness/80-sessions/nixos-13-outage-postmortem-nixos-rebuild-switch-broke-static|NixOS .13 outage postmortem: nixos-rebuild switch broke static network via NetworkManager race]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-35-2026-11-12-03-14-45|Rich discovery: .35 2026-11-12 03:14:45]]
 - context: [[packs/paperclip-harness/20-context/nix|.35]]
+
+
+---
+
+## Update (2026-11-12 03:29:14)
+
+Trigger: one user-level package (e.g. `pi-coding-agent`) must be a specific version across several NixOS hosts without moving the system nixpkgs pin.
+
+Prerequisites: repo per host (`nixos-desktop`, `nixos-4screen`, `nixos-thinkpad`) cloned at `/etc/nixos`; a known-good nixpkgs commit for the desired package version.
+
+Steps:
+1. In each host's `flake.nix`, add input `nixpkgs-pi.url = "github:NixOS/nixpkgs/<commit>";` and in the per-system outputs `piPkgs = import nixpkgs-pi { inherit system; config.allowUnfree = true; };` (allowUnfree needed if the package is unfree).
+2. In the home-manager users block, add `piPkgs.<pkg>` to `home.packages`.
+3. Remove any duplicate of the same package from `home/sam/home.nix` — otherwise two versions land on PATH and the result is ambiguous.
+4. Back up touched files (`cp flake.nix flake.nix.bak-<tag>` etc.) before editing.
+5. Verify WITHOUT switching: `nix build` the full system on each host and read the package's store path from the result (e.g. inspect `result/sw/bin/<pkg>` or `result/home-path`/home-manager generation links).
+6. Treat identical store paths across hosts as the success criterion; a matching `--version` string is not sufficient.
+7. Only if the system nixpkgs pin is unmoved (user-package-only change): `sudo nixos-rebuild switch --flake /etc/nixos#<host>` is acceptable. Otherwise use `nixos-rebuild boot` + reboot.
+8. Confirm with `<pkg> --version` on each host after activation.
+
+Danger/caveats:
+- Never `switch` a nixpkgs-sized change on an in-use or remote host; use `boot` + reboot.
+- Exit code 4 from `nixos-rebuild switch` means units failed to start, not build failure — the generation may already have switched; check the running generation before retrying.
+- If a prior lockfile bump broke full-system builds on a host, restore that host's `flake.lock` before layering the new pin.
+
+Rollback: restore the `.bak-*` files and `git checkout` the previous commit per repo; `nixos-rebuild switch --flake /etc/nixos#<host>` to the prior generation, or reboot into it.
+
+## Evidence
+
+- Confidence: 85%
+- Reason: Repeatable multi-host procedure with explicit verification, safe/dangerous commands, and rollback.
+
+## Related learned memories <!-- same-turn-2026-11-12 03:29:14 -->
+
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|Host roles, repos, and Pi drift on the NixOS lab (192.168.20.x)]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Pinning a user package to a separate nixpkgs input and verifying store-path equality across hosts]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Use nixos-rebuild boot (not switch) for nixpkgs-sized changes on in-use hosts; pin Pi via a separate nixpkgs-pi input]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Aligned Pi to 1.5.0 across .13/.27/.51 and pushed four repos]]
+- session: [[packs/paperclip-harness/80-sessions/pi-1-5-0-alignment-across-three-nixos-hosts-via-pinned-nixpk|Pi 1.5.0 alignment across three NixOS hosts via pinned nixpkgs-pi input]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-nixos-2026-11-12-03-29-14|Rich discovery: NixOS 2026-11-12 03:29:14]]
+- context: [[packs/paperclip-harness/20-context/home|NixOS]]