2026 cleanup

AGENTS.md

@@ -0,0 +1,76 @@
+# Agent Guide
+
+This repository builds and deploys OpenBSD VPN servers on Google Cloud. The goal is to make it easy to create multiple VPN VMs in two flavors:
+
+- WireGuard, matching the existing historical deployment in `server/`.
+- IPsec, using OpenBSD `iked`/`ipsecctl`.
+
+Keep this repository focused on VPN server definitions, provisioning glue, firewall rules, and run commands. The local `skz-opack/` directory is an ignored dependency that provides the OpenBSD image/build/deploy Makefile interface. Read it when you need to understand `OPACK_*` variables or targets, but do not modify it unless the user explicitly asks for dependency work.
+
+## Repository Shape
+
+- `server/` is the current WireGuard deployment. It includes the OpenBSD install disklabel, provisioning script, GCP firewall overlay, and Makefile using `../skz-opack/src/opack.mk`.
+- `src/` is early IPsec/iked work and should stay separate from WireGuard-specific provisioning.
+- Future VPN servers should live in separate directories or separate Makefiles. Do not merge WireGuard and IPsec into one opaque shared Makefile until real duplication justifies it.
+- Each server definition should declare its own `OPACK_TARGET`, hostname, GCP project/key settings, provision script, firewall rules, client list, and generated-state ignore patterns.
+
+## Tools And Installation
+
+Before build or deployment work, verify the required host tools:
+
+```sh
+for x in make jq python3 rg curl git ssh scp nc vagrant packer terraform gcloud qemu-system-x86_64; do command -v "$x" || echo "missing: $x"; done
+```
+
+In sloptrap/Codex containers, install missing third-party tools under `/sloptrap-tools` and expose executables through `/sloptrap-tools/bin`, which is already on `PATH`. Do not install toolchains into this repo, `$HOME`, or one-off directories.
+
+Use `/sloptrap-tools` for SDKs, plugins, and caches when configurable. For example, a Google Cloud SDK install may live under `/sloptrap-tools/google-cloud-sdk` with `/sloptrap-tools/bin/gcloud` symlinked to the real executable. Keep Packer plugin caches and similar generated tool state under `/sloptrap-tools` when possible.
+
+## Secrets And Live State
+
+`server/` may contain ignored live credentials and generated deployment state:
+
+- `id_ed25519`
+- `skz-void-bbb88f038188.json`
+- `opack-cloud`
+- `opack_deploy_*`
+- `opack_installer_*`
+
+Never commit, print, copy into tracked files, rotate, delete, or regenerate these files unless the user explicitly asks. Treat them as live operational material.
+
+Agents may SSH for read-only diagnostics when useful, using the ignored key and current deployed IP:
+
+```sh
+ssh -i server/id_ed25519 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null root@$(cat server/opack-cloud) 'uname -a; sysctl kern.version'
+```
+
+Do not change services, firewall rules, VPN keys, GCP resources, package state, or deployed configuration on the live VM without explicit user approval.
+
+## Workflows
+
+For existing WireGuard deployment work, the main entrypoint is:
+
+```sh
+make -C server void
+```
+
+This is not a harmless check. It may build an OpenBSD image, run Terraform, apply firewall rules, copy the external `skz-wg` tree to the live VM, and run remote provisioning. Use it only when the user wants deployment or provisioning work.
+
+For read-only live inspection, prefer direct SSH commands and report exactly what was inspected. Avoid broad commands that dump secrets or large config files.
+
+For future IPsec work, use OpenBSD-native `iked`/`ipsecctl` conventions. Keep IPsec provisioning, firewall rules, client/certificate generation, and run targets separate from WireGuard. Make IPsec firewall allowances explicit instead of reusing the WireGuard UDP rule.
+
+For future multi-server work, prefer adding a new isolated server directory or Makefile that includes `../skz-opack/src/opack.mk` and overrides `OPACK_*` values before the include. Keep generated files ignored next to the server that creates them.
+
+## Validation
+
+For documentation-only changes, validate with:
+
+```sh
+sed -n '1,240p' AGENTS.md
+git diff -- AGENTS.md
+```
+
+Do not run deployment targets as documentation validation.
+
+For Makefile/provisioning changes, use the narrowest non-destructive validation first, such as reading expanded Make variables, shell syntax checks, or targeted dry-run inspection. Treat `make ... opack-cloud`, `make -C server void`, Terraform apply/destroy, and remote provisioning commands as live infrastructure changes.