# AGENTS.md

Development conventions for the compose repository (Docker Compose stacks).

## Build & Deploy

- The ai stack is managed via `systemctl restart ai_stack.service` on the NixOS host
- Compose files are built from the git repo; apply via `nh os switch` or `systemctl restart ai_stack.service`
- Never `docker compose up -d` directly — it bypasses the systemd env file and breaks secrets

## Hermes Workers

- Paperclip Hermes workers are added via `ai/scripts/provision-hermes-worker.sh`
- The script appends only — never deletes or modifies existing content
- Workers are CPU-only containers on the `ai_backend` network with no GPU passthrough

## Workflow

- New feature → clean branch from `origin/master` → push → PR on Gitea
- Branch naming: `feat/description` (features), `fix/description` (bugs/docs)
- Always branch from `origin/master`, never from another feature branch
- Submodule changes (when this repo is consumed as a submodule): commit the submodule update in the parent repo
- PR title should describe the change; body should explain motivation + summary
- After PR merge, delete the feature branch

## YAML Conventions

- Use `x-*` extension fields for reusable anchors
- Comment out inactive services rather than deleting them
- Environment variables in dictionary format (`KEY: value`) for anchor compatibility
- List format (`- KEY=value`) works for standard services but doesn't merge with anchors