# Agent Guidelines

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

## 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/`](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 `localuser` with passwordless sudo
  on all hosts.
- **SSH in Crush**: Direct ssh/scp is blocked in the Crush bash environment.
  Use the wrapper scripts: [`tests/remote.sh`](tests/remote.sh),
  [`dns-cluster-setup/remote-dns.sh`](dns-cluster-setup/remote-dns.sh),
  or the `perf/deploy-check.sh` / `perf/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 — do not wait to be
asked.** After each logical unit of work:

1. Stage only the files belonging to that logical change.
2. Commit with a conventional, well-formed message.
3. Push to `origin` (`git push`). The branch tracks `origin/main`.
4. Repeat per logical unit.

Group changes so each commit is coherent on its own (a reader should
understand the commit without seeing the others). Never batch unrelated
changes into one commit.

## Key scripts

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

## Key documentation

| Doc | Contents |
|-----|----------|
| [`docs/PROJECT.md`](docs/PROJECT.md) | Comprehensive fleet report (7 hosts, VM inventory, storage) |
| [`docs/SECURITY.md`](docs/SECURITY.md) | Security architecture and hardening details |
| [`docs/tailscale.md`](docs/tailscale.md) | Tailscale vs managed DNS analysis (resolved) |
| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Deployment procedures |
| [`docs/TODO.md`](docs/TODO.md) | Pending hardware work (tsys2/4/5) |
| [`docs/K8S.md`](docs/K8S.md) | Kubernetes architecture deep-dive |
| [`dns-cluster-setup/README.md`](dns-cluster-setup/README.md) | DNS cluster setup guide |
| [`tests/README.md`](tests/README.md) | Test suite documentation |

## 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`](docs/PROJECT.md) for the comprehensive fleet report and
[`docs/TODO.md`](docs/TODO.md) for pending hardware work.