74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
---
|
|
name: nixos-workflow
|
|
description: STRICT workflow for managing Pi assets via Gitea on NixOS
|
|
version: 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`:
|
|
```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
|