From c6ce1f4901d009f836376536fcd0a6bd11b7f58f Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Sun, 1 Mar 2026 11:20:02 -0500
Subject: [PATCH] docs: add DigitalOcean VPS verification guidance

---
 AGENTS.md | 15 +++++++++++++++
 CODEX.md  |  1 +
 2 files changed, 16 insertions(+)
 create mode 120000 CODEX.md

diff --git a/AGENTS.md b/AGENTS.md
index c9dff09..c350daa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,6 +70,21 @@ sudo baudbot update
 sudo baudbot rollback previous
 ```
 
+## Real Linux verification (DigitalOcean)
+
+When you have a DigitalOcean API credential available, you are encouraged to validate behavior on a real Linux VPS (not only local/sandbox runs), especially for runtime, process, tmux/session-control, networking, firewall, installer, or permissions-related changes.
+
+- Treat `DO_API_KEY` as a DigitalOcean token alias. This repo's scripts use `DO_API_TOKEN` as the canonical variable.
+- Prefer **Arch Linux** for first-pass verification when possible (lighter/faster CI baseline in this repo).
+- Reuse existing droplet helpers instead of ad-hoc scripts:
+  - `bin/ci/droplet.sh create ...`
+  - `bin/ci/droplet.sh wait-ssh ...`
+  - `bin/ci/droplet.sh run ... bin/ci/setup-arch.sh`
+  - `bin/ci/droplet.sh destroy ...`
+- For Arch image defaults, use the same image/version strategy as `.github/workflows/integration.yml`.
+- Always destroy temporary droplets/SSH keys/images after verification to avoid cost leaks.
+- Never print or persist DigitalOcean credentials in logs, commits, or memory files.
+
 ## Non-negotiable guardrails
 
 **Hard constraints (enforced by pre-commit hook or CI):**
diff --git a/CODEX.md b/CODEX.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CODEX.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file