# AGENTS.md — Agent Workflows

Read [CLAUDE.md](CLAUDE.md) first for safety rules and technical context.

## Common Workflows

### Add a Detection Function

1. Add the function to `lib/detect.sh` following `detect_*` naming convention
2. If it reads sysfs, use `$GPU_SYSFS` (auto-detected) with a `2>/dev/null` fallback
3. Wire it into `scripts/audit/quick-glance.sh` (display) and/or `scripts/audit/system-report.sh` (JSON output)
4. If it has an optimal value, add a check to `scripts/optimize/verify.sh`
5. Validate: `make audit` and `bin/audit --json | python3 -m json.tool`

### Add a Benchmark Backend

1. Add the toolbox entry to `BENCH_PATHS` associative array in both `scripts/benchmark/run-baseline.sh` and `scripts/benchmark/run-suite.sh`
2. Map the toolbox name → llama-bench binary path (Vulkan: `/usr/sbin/llama-bench`, ROCm: `/usr/local/bin/llama-bench`)
3. If ROCm, the `ENV_ARGS` logic already handles `ROCBLAS_USE_HIPBLASLT=1`
4. Add the toolbox to `refresh-toolboxes.sh` in the [toolboxes repo](https://github.com/kyuz0/amd-strix-halo-toolboxes)
5. Validate: `make benchmark-setup` then `make benchmark`

### Add an Optimization Script

1. Create `scripts/optimize/my-optimization.sh` sourcing `lib/common.sh` (and `detect.sh` / `format.sh` as needed)
2. Add root check at top if the script modifies system state: `[[ $EUID -ne 0 ]] && { log_error "Requires root"; exit 1; }`
3. Add a corresponding case to `bin/optimize`
4. Add a Makefile target
5. Add verification criteria to `scripts/optimize/verify.sh`
6. If the optimization is reversible, add rollback logic to `scripts/optimize/rollback.sh`
7. Document in [docs/optimization.md](docs/optimization.md)

### Add a Monitoring Metric

1. In `scripts/monitor/log-metrics.sh`, cache the sysfs path at startup (avoid per-sample globbing)
2. Read with `read -r var < "$SYSFS_PATH" 2>/dev/null || var=0` (no subshells in the hot loop)
3. Add the column to the CSV header and the `echo` line
4. Update the CSV schema in [docs/architecture.md](docs/architecture.md)

## File Responsibility Map

| Want to change... | Touch these files |
|-------------------|-------------------|
| What `make audit` shows | `scripts/audit/quick-glance.sh`, `lib/detect.sh` |
| JSON audit output | `scripts/audit/system-report.sh`, `lib/detect.sh` |
| Dashboard layout | `scripts/monitor/dashboard.sh` |
| Metric collection | `scripts/monitor/log-metrics.sh` |
| Benchmark parameters | `scripts/benchmark/run-baseline.sh`, `run-suite.sh` |
| Result comparison | `scripts/benchmark/compare.sh` |
| Kernel params | `scripts/optimize/kernel-params.sh`, `lib/detect.sh` (recommended values) |
| Optimization checks | `scripts/optimize/verify.sh`, `scripts/audit/quick-glance.sh` |
| Shared utilities | `lib/common.sh` (logging), `lib/format.sh` (output), `lib/detect.sh` (hardware) |
| External links | `docs/references.md` (single source of truth) |

## Dependencies by Workflow

| Workflow | Requires |
|----------|----------|
| Audit | `bc`, `python3` |
| Monitor | `tmux`, `amdgpu_top` or `nvtop`, `btop` or `htop` |
| Benchmark | `toolbox`, `podman`, GGUF models in `data/models/`, `python3` |
| Optimize | `sudo`/root, `grubby` or `grub2-mkconfig`, `tuned-adm`, `python3` |