# Agent Guidelines

This repo combines two formerly-separate projects:
- **Server provisioning** (formerly KNELServerBuild): `provisioning/`, `tests/`,
  `vendor/`, `dns-cluster-setup/`
- **Proxmox cluster ops** (formerly PFVCluster/perfopt): `perf/`, `netinfra/`,
  `switches/`, `returned-logs/`

## Repository Layout

- **Vendored framework**: `KNELShellFramework` lives at
  `vendor/git@git.knownelement.com/29418/KNEL/KNELShellFramework/`. Its includes
  are under `Framework-Includes/` there. Never assume `./Framework-Includes`
  exists relative to the repo root.
- **Self-locating scripts**: All provisioning scripts derive their own location
  via `BASH_SOURCE` and compute `PROJECT_ROOT_PATH` from it. They must never
  depend on the current working directory. Run from anywhere.
- **Local config files are the source of truth**: Configs in
  `provisioning/ConfigFiles/` are read with `cat`/`cp`. Do NOT re-introduce
  `curl ${DL_ROOT}/...` downloads — that CDN is deprecated.
- **Non-bash agents**: Some files under `provisioning/Agents/` carry a `.sh`
  extension but are PHP (e.g. `mysql.sh`, shebang `#!/usr/bin/php`). Syntax
  checkers must skip these.
- **Proxmox hosts** are standalone installs managed via **PDM** (Proxmox
  Datacenter Manager). SSH keys deployed to root on all hosts.
- **SSH in Crush**: Direct ssh/scp is blocked in the Crush bash environment.
  Use the wrapper scripts: `tests/remote.sh`, `dns-cluster-setup/remote-dns.sh`,
  or the `deploy-check.sh` / `deploy-tuning.sh` patterns.

## Git Commit Requirements

1. **Commit atomically**: each logical change its own commit.
2. **Conventional commit format**: `feat(scope): desc`, `fix(scope): desc`,
   `docs: desc`, `refactor(scope): desc`, `test(scope): desc`, `chore: desc`.
3. **Verbose messages**: title (50 chars max), blank line, body explaining
   WHAT and WHY, footer with attribution.

## Autonomous Git Workflow

Agents are authorized to commit AND push autonomously. After each logical unit
of work: stage, commit, push to `origin/main`. Group changes so each commit is
coherent on its own.

## Key scripts

| Script | Purpose |
|--------|---------|
| `provisioning/SetupNewSystem.sh` | Full server provisioning (packages, hardening, 2FA) |
| `tests/vm-validation.sh` | End-to-end deploy + validate on sandbox VM |
| `tests/run-tests.sh` | Project test suite (unit/security/validation) |
| `dns-cluster-setup/setup.sh` | Technitium DNS cluster replication |
| `perf/deploy-check.sh` | Deploy read-only data collector to hosts |
| `perf/deploy-tuning.sh` | Deploy perf tunings to hosts |
| `perf/validate-fixes.sh` | Validate applied tuning changes |
| `perf/iperf-full-matrix.sh` | Full iperf throughput suite |

## Project context

This is a solo-founder R&D Proxmox cluster in a private residence. Shoestring
budget. Redundancy is not a concern for the R&D cluster. Backups DO matter
(PBS in use). Production lives on a VPS in Reston VA (Cloudron). See
`docs/PROJECT.md` for the comprehensive fleet report and `docs/TODO.md` for
pending hardware work.