# AGENTS.md

## 1. Overview

Container image for Hermes Agent WebUI with a bundled Hermes Agent runtime, distributed via Docker Hub as `jcabillot/hermes-agent-webui`.

## 2. Folder Structure

- `Dockerfile`: Multi-stage image build — clones `nousresearch/hermes-agent` and `nesquena/hermes-webui`, installs both in a shared venv, copies to a slim runtime stage. Exposes port `8787`.
- `.gitea/workflows/docker-build.yaml`: Gitea Actions pipeline — builds and pushes the image to Docker Hub on push to `main` and on a daily cron schedule.
- `renovate.json`: Regex-based custom manager tracking upstream `nousresearch/hermes-agent` and `nesquena/hermes-webui` Docker tag updates.
- `README.md`: Public-facing documentation.
- `AGENTS.md`: This file — contributor guide for AI agents.

## 3. Core Behaviors & Patterns

- **Build & Release**: The Dockerfile pins two upstream repos via `ARG HERMES_AGENT_VERSION` and `ARG HERMES_WEBUI_VERSION`. On push to `main`, the CI pipeline builds the image, bumps the git tag (`patch`), which triggers a tag release that pushes to `jcabillot/hermes-agent-webui`. A daily cron rebuild pushes `<latest-tag>-latest`.
- **Dependency Tracking**: Renovate scans `Dockerfile` for both `ARG` version pins and opens PRs when either upstream publishes a new tag.
- **Multi-stage Build**: Build stage clones repos and creates a venv; runtime stage is a clean `python:3.12-slim` with only the venv and source trees copied over.
- **Health Check**: The container exposes port `8787` with a `/health` endpoint polled every 30s.

## 4. Conventions

- **Version Pinning**: Both upstream versions (`HERMES_AGENT_VERSION`, `HERMES_WEBUI_VERSION`) are pinned via `ARG` at the top of the builder stage, managed by renovate.
- **CI Secrets**: `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, `SA_TOKEN_ACTION_PUSH_TAGS` required. Login skipped on PR events.
- **Dockerfile Style**: Multi-stage with `AS builder` / runtime split. `apt-get` in a single `RUN` with cleanup. `COPY --from=builder` for artifacts. Comments annotate stage boundaries.
- **Pin Hashing**: All GitHub Action versions pinned to commit SHA hashes with semantic version in trailing comment.

## 5. Working Agreements

- Respond in the user's preferred language (French or English); keep technical terms in English, never translate code blocks
- Create tests/lint only when explicitly requested
- Build context by reviewing related usages and patterns before editing
- Prefer simple solutions; avoid unnecessary abstraction
- Ask for clarification when requirements are ambiguous
- Make minimal changes; preserve public APIs and behavior
- Run type-check after code changes (no type-checker in this project — skip)
- New files: single-purpose, colocated with related concerns
- External dependencies: only when necessary, explain why