pi-config/skills/nixos-workflow/SKILL.md

name, description, version

name	description	version
nixos-workflow	STRICT workflow for managing Pi assets via Gitea on NixOS	1.1.0

NixOS Gitea Asset Manager (STRICT)

You are an expert at managing Pi Agent assets on a NixOS system using a Gitea-centric workflow.

⛔ CRITICAL PROHIBITIONS

• NEVER suggest or perform edits to home.nix to add individual extensions or skills.
• NEVER use pi install or npm install -g (Nix store is read-only).

🛠 THE SOURCE OF TRUTH

All assets MUST be managed in the local Git-controlled directory:

• Local Path: /home/sam/.agents
• Remote URL: https://gitea.lab.audasmedia.com.au/sam/pi-config

🏗 ASSET DEPLOYMENT WORKFLOW

When the user asks for a new tool or skill, you MUST follow these steps exactly:

1. Local Authoring:
   • Write code/markdown directly into the appropriate subfolder in ~/.agents/ (e.g., extensions/ or skills/).
   • If cloning an external repo, immediately rm -rf .git inside that folder to prevent submodule issues. Also inside that folder remove '.gitignore' if it is there.
2. Local Dependency Check:
   • If an extension, run npm install inside that specific subfolder.
3. Gitea Synchronization:
   • cd /home/sam/.agents
   • git add .
   • git commit -m "Add [asset name]"
   • git push origin main
4. Project Activation:
   • Instruct the user to add the relative path (e.g., "extensions/my-tool/index.ts") to their current project's .pi/settings.json.

❄ NIXOS INTEGRATION

The ONLY time you reference Nix is for the Global Settings. Confirm the user's home.nix contains a settings.json that points to the Gitea source: "source": "git:https://gitea.lab.audasmedia.com.au/sam/pi-config"

🖥 PI INSTALLATION CONTEXT

On this system, pi is a shell script wrapper defined in home.nix:

${pkgs.nodejs_24}/bin/npx @mariozechner/pi-coding-agent "$@"

• pi update --self will always fail — npx manages freshness automatically; pi update --extensions works fine.
• To force a fresh version: clear the npx cache (npx clear-cache) or just run npx @mariozechner/pi-coding-agent --version.
• Global npm install does NOT apply here — NixOS manages the wrapper, not npm install -g.
• Do not suggest npm install -g @mariozechner/pi-coding-agent — it would conflict with the Nix-managed wrapper.
• The binary runs from: /home/sam/.npm/_npx/<cache-hash>/node_modules/.bin/pi (npx cache, not a managed install).

⌨ KEYBOARD TROUBLESHOOTING (Corne/QMK)

The user has a Corne-like QMK keyboard. These are critical things to remember:

Caps lock stuck ON

If all letters output uppercase and Shift inverts to lowercase, the Lower/Raise layer keys may be reversed in the keymap. Do NOT suggest hardware resets or firmware flashing.

Fix: Use VIA Web at https://usevia.app — it works immediately in Chrome via WebHID (no install needed). The user can identify and remap misconfigured keys there.

udev setup for VIA/Vial Web

Required in configuration.nix:

services.udev.extraRules = ''
  KERNEL=="hidraw*", SUBSYSTEM=="hidraw", GROUP="input", MODE="0660"
'';
users.users.sam.extraGroups = [ "input" ];

After rebuild, unplug/replug the keyboard for permissions to take effect.

Vial desktop app — DO NOT recommend

• The nixpkgs vial package wraps an AppImage with no Qt5 Wayland support
• It fails with Could not connect to any X display
• VIA Web (usevia.app) provides identical functionality without native dependencies
• Only suggest the desktop app if the nixpkgs package has been proven to work on Wayland