Files

T

mrcharles a7fbad60ab docs: end-to-end gardening — links, stale refs, tailscale.md update

Comprehensive documentation gardening across the merged repo:

- tailscale.md: fully rewritten with current ground truth. The netinfra
  pair now runs production Technitium with all knel.net records
  replicated. Both LAN IPs resolve knel.net device names and recurse
  externally. The old "NXDOMAIN / zone is stale" findings are replaced
  with the resolved state and current recommendations.
- AGENTS.md: rewritten with Gitea-compatible clickable relative links
  to all key scripts and docs. Autonomous commit/push policy
  prominently documented. SSH user corrected to localuser.
- README.md: directory table and docs table now use clickable links.
- All .md cross-references converted to Gitea-renderable relative links.
- Stale path references (ProjectCode/, Project-Tests/, ProjectDocs/)
  updated to current names (provisioning/, tests/) across all docs.
- Stale repo name "FetchApply" / "KNELServerBuild" updated to
  "PFVCluster" in actionable docs; historical AI-review docs tagged
  with an HTML comment notice.
- REFACTORING-EXAMPLES.md: tagged as historical (pre-refactor patterns).
- tests/README.md, dns-cluster-setup/README.md, docs/DEPLOYMENT.md,
  docs/SECURITY.md: path references fixed to current structure.

🤖 Generated with [Crush](https://github.com/charmassociates/crush)

Assisted-by: GLM-5 via Crush <crush@charm.land>

2026-07-28 11:28:52 -05:00

4.4 KiB

Raw Blame History

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/

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 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, dns-cluster-setup/remote-dns.sh, or the perf/deploy-check.sh / perf/deploy-tuning.sh patterns.

Git Commit Requirements

Commit atomically: each logical change its own commit.
Conventional commit format: feat(scope): desc, fix(scope): desc, docs: desc, refactor(scope): desc, test(scope): desc, chore: desc.
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:

Stage only the files belonging to that logical change.
Commit with a conventional, well-formed message.
Push to origin (git push). The branch tracks origin/main.
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`	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

Key documentation

Doc	Contents
`docs/PROJECT.md`	Comprehensive fleet report (7 hosts, VM inventory, storage)
`docs/SECURITY.md`	Security architecture and hardening details
`docs/tailscale.md`	Tailscale vs managed DNS analysis (resolved)
`docs/DEPLOYMENT.md`	Deployment procedures
`docs/TODO.md`	Pending hardware work (tsys2/4/5)
`docs/K8S.md`	Kubernetes architecture deep-dive
`dns-cluster-setup/README.md`	DNS cluster setup guide
`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 for the comprehensive fleet report and docs/TODO.md for pending hardware work.

4.4 KiB Raw Blame History