# AGENTS.md

This file provides guidance to AI assistants (Claude, Gemini, Copilot, OpenCode etc.) when working with code in this
repository.

## Project Overview

Panther Minor is a self-hosted AI workstation setup designed for running LLMs and AI services on
AMD hardware with ROCm support. It includes configurations for llama.cpp, stable-diffusion.cpp, Open WebUI, Prometheus,
Grafana, and exporters for monitoring GPU and node performance.

## Stack

- **Host**: Ubuntu 26.04 LTS+ (Linux kernel 7), ROCm 10, kernel params `amdgpu.mes=1 iommu=pt`
- **Services**: llama.cpp, llama-manager (proxy/idle unloader), stable-diffusion.cpp (sd-server image generation),
  sd-manager (proxy), Open WebUI, Prometheus, Grafana, GPU/node exporters
- **Network**: See `docs/networking.md`. SSH on 2222, services on 3000/5000/8000/8001/8080/9090
- **Config**: `.env` (from `.env.example`), `docker-compose.yml`, `cli/*`

## Critical Rules

1. **Code Style** – Ultracite preset for Biome, Prettier (shell included, via `prettier-plugin-sh`) and ShellCheck (use `pnpm run check` or `pnpm run fix` to check or auto-fix)
2. **Custom ROCm builds only** — llama.cpp (`llama-cpp/Dockerfile`) for LLMs and stable-diffusion.cpp (`stable-diffusion-cpp/Dockerfile`) for image generation, both ROCm v10 with `gfx1201` support
3. **Package manager** — `apt-get` only in scripts and Dockerfiles (never `apt`): `apt` has no stable CLI interface and warns on every scripted call. Use `apt-get upgrade --with-new-pkgs` where `apt upgrade` was meant, and `apt-cache`/`apt-mark` for queries
4. **Commits** — Conventional Commits v1.0.0, lowercase, no final punctuation, 100 chars max

## Key Files

- `README.md` — minimal project overview, quick start, ownership; links to `docs/`
- `docs/README.md` — documentation index; one domain per file in `docs/` (follow its conventions when adding or editing docs)
- `docs/networking.md` — port configuration, `BIND_ADDR`, and access methods
- `docs/cli.md` — `./bin/panther-minor` command reference and maintainer workflow (strictly follow rules there for CLI changes)
- `docs/models.md`, `docs/llm.md`, `docs/image-generation.md` — model catalogs and shared cache; LLM serving (`./bin/panther-minor models llm *`, `models/llm.config.json`, `llama-cpp/preset.ini`); text-to-image (`./bin/panther-minor models t2i *`, `models/t2i.config.json`)
- `docker-compose.yml` — service definitions with health checks
- `release/package.sh` — the runtime file set every host install ships (release archive and branch updates); add new runtime files here. `release/install.sh` is the curl installer uploaded with each release
- `llama-cpp/manager.js` — activity-aware reverse proxy; records inference activity, exposes `/status` for the exporter; unloads idle models and arbitrates large-model switches before proxying inference
- `llama-cpp/models.js` — shared model helpers, including normalization and the static list of model IDs treated as large by the manager
- `llama-cpp/metrics-exporter.js` — Prometheus exporter; queries `llama-manager /status` to decide idle vs. active scrape cycle
- `stable-diffusion-cpp/Dockerfile` + `entrypoint.sh` — builds `sd-server` (ROCm/HIP, gfx1201) and serves Ideogram 4 with an OpenAI-compatible image API
- `stable-diffusion-cpp/manager.js` — thin activity-tracking reverse proxy in front of `sd-server` (no model unload; `sd-server` has none), exposes `/status`
- `stable-diffusion-cpp/metrics-exporter.js` — Prometheus exporter deriving `sd_*` gauges from `sd-manager /status` and `sd-server /v1/models`
- `monitoring/prometheus.yml` — node, GPU, llama.cpp, and stable-diffusion.cpp exporter targets for Prometheus
- `monitoring/grafana/dashboards/gpu.json` — Grafana dashboard for GPU metrics

## Planning

When requested to plan a new feature or change, provide a clear outline that can be reviewed and approved before implementation.
It should also be a complete guide to any agent taking over the work and implementing it. Go straight to the point, and avoid unnecessary verbosity.
Each plan is written in a separate file in the `.agents/plans` directory, with a name constructed as `YYYY-MM-DD-<short-description>.md`.