From 586ba78daf9f40e9dc6b0fce0137b8f6d76baa26 Mon Sep 17 00:00:00 2001
From: John Bargman
Date: Wed, 15 Apr 2026 05:44:12 +0000
Subject: add AGENTS.md with deployment commands and gotchas

Core commands: nix flake check, build, nixinate deploy, remote-command
Key gotchas: --option builders '', Secrix validation, deprecated options---
 AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4e25ed9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,47 @@
+# AGENTS.md - CrashOverBurn Web Server
+
+## Core Commands
+
+```bash
+# Validate flake (ALWAYS use --option builders '')
+nix flake check --option builders ''
+
+# Build system derivation
+nix build .#nixosConfigurations.crash-over-burn-1.config.system.build.toplevel --option builders ''
+
+# Deploy (nixinate - the CORRECT deployment tool, never replace it)
+nix run .#crash-over-burn-1
+
+# Run remote command on crash-over-burn-1 (193.16.42.36:1108)
+nix run .#remote-command -- "<command>"
+
+# Validate Secrix recipients
+nix run .#secrix -- -l
+```
+
+## Key Facts
+
+- **Deployment target**: 193.16.42.36, port 1108, user: commander
+- **Services**: cgit, ejabberd (XMPP), murmur (Mumble), movim (social), mailserver, nginx
+- **Secrets**: Encrypted via age/Secrix in `secrets/`
+- **State persisted**: `/persist/` directories
+
+## Gotchas
+
+1. **Nixinate is NOT legacy**. It is the bleeding edge of correct deployment tools. Never suggest replacing it with `nixos-rebuild`.
+
+2. **Always use `--option builders ''`** with nix commands per fleet directives.
+
+3. **Secrix encryption requires both user AND host key** - validate with `nix run .#secrix -- -l` before deploying.
+
+4. **Deprecated options**:
+   - `services.xserver.layout` → `services.xserver.xkb.layout`
+   - `devShell` → `devShells.x86_64-linux.default`
+
+5. **Verify cgit** via: `nix run .#remote-command -- "systemctl status uwsgi"`
+
+## Reference
+
+- Core guideline: `/speed-storage/opencode/llm/shared/common-infra-strategies.md`
+- Deployment docs: `docs/deployment.md`
+- Phase plan: `docs/PHASE_EXECUTION_PLAN.md`
\ No newline at end of file
-- 
cgit v1.2.3