1 files changed, 82 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d88d7ed
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,82 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this repo is
+
+`statuspage/` generates a static status console for a FreeBSD homelab
+server (`dandokmang.com`). Modular POSIX `/bin/sh` check scripts each emit
+JSONL rows; an orchestrator (`render.sh`) runs them all, groups the rows by
+section, and writes a static `index.html` (dark/monospace, stoplight-grid
+style) that Caddy serves over WireGuard.
+
+**Start with `statuspage/README.md`** for the full JSONL contract between
+check scripts and the renderer, the jails-are-auto-discovered-not-scripted
+design, failure-isolation behavior, and the current deployment recipe
+(Caddy + DNS-01 cert via Porkbun). This file only covers what that one
+doesn't: workflow and environment gotchas specific to developing here.
+
+## Where code runs vs. where it's edited
+
+This checkout is on Windows. None of the runtime commands the check
+scripts depend on (`sysctl`, `jls`, `jexec`, `pfctl`, `zpool`, `wg`,
+`service`, `ntpq`) exist here - they only exist on the target FreeBSD box.
+
+- **Validate here**: `sh -n path/to/script.sh` for syntax, and dry-run
+  logic by putting small shell stubs for the real commands in a temp dir
+  and prepending it to `PATH` (e.g. a fake `pfctl` that echoes canned
+  output). This is the only way to exercise check-script logic without
+  the real box.
+- **Deploy for real**: this repo's `origin` remote is
+  `ssh://cgit-jail/srv/git/console.git`. The FreeBSD server has its own
+  clone at `~/projects/console`, with `/usr/local/etc/statuspage`
+  symlinked to `~/projects/console/statuspage`. `render.sh` runs there via
+  root cron every minute, writing to `/usr/local/www/status/index.html`.
+  Changes only take effect after: commit here -> push -> `git pull` on the
+  server. There is no way to verify a change actually works against real
+  system state from this machine - say so rather than claiming success.
+
+## Committing shell scripts
+
+`core.fileMode` is `false` on this checkout, because this Windows
+filesystem doesn't reliably preserve the executable bit - `chmod +x`
+followed by a plain `git add` still stages a `.sh` file as `100644`.
+
+`git config core.hooksPath .githooks` (already set in this checkout, but
+**not** carried by a fresh clone - re-run it once after cloning elsewhere)
+activates a pre-commit hook that force-sets `+x` on every staged `*.sh`
+file automatically. A non-`.sh` executable (rare - the hook only globs
+`*.sh`) needs `git update-index --chmod=+x <file>` by hand, and so does
+the hook file itself if it's ever edited (it can't fix its own bit).
+
+## Gotchas already hit once - don't re-discover these
+
+- **`ln -s` on a directory, tested on this Windows box, silently falls
+  back to a real copy instead of a symlink.** Don't trust symlink
+  behavior verified here; it needs confirming on the real FreeBSD box.
+- **Greedy regex substring traps**: `usec` contains `sec`, so
+  `sed 's/.*sec = \(...\).*/.../'` will match the *last* occurrence
+  (`usec`), not the first. Anchor tightly (e.g. match the literal `{ sec
+  = ` prefix) instead of relying on `.*` to stop at the right spot.
+- **`ntpq`'s `rv 0 offset` prefixes non-negative values with a literal
+  `+`.** A sed capture class of `[-0-9.]` silently drops the `+` and
+  matches empty rather than failing loudly - always include `+` alongside
+  `-` in numeric-capture character classes.
+- **`grep -c pattern` exits `1` when the count is `0`**, even though it
+  prints `0`. Guard command substitutions that end in `grep -c` with
+  `|| var=0`, or `set -e` will kill the whole script on a legitimate
+  zero-count case.
+- **Most check commands (`pfctl`, `jls`, `wg`, `jexec`) need root.**
+  `render.sh` runs as root via cron, so this isn't an issue in production,
+  but manual testing on the box needs `doas`/`sudo`.
+
+## Cosmetic conventions (render.sh)
+
+- Status values are `ok` / `warn` / `down` (green/yellow/red) or `info`
+  (gray, for rows that aren't a health signal - e.g. `pf.sh`'s rule
+  listing). Don't repurpose the health colors for non-health rows.
+- The font (`statuspage/fonts/scientifica.ttf`, a bitmap-style font) only
+  ships Arrows, Geometric Shapes, Box Drawings, Mathematical
+  Operators/Symbols-A, Misc Technical/Symbols, and PUA/Powerline glyphs -
+  notably **not** Dingbats (✓/✗). Check glyph coverage against that list
+  before adding new symbols to check-script output.