compose/AGENTS.md

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