docs: record the visual identity in DESIGN.md

DESIGN.md states the two rules that carry the board's identity (big value
at the card's top-right, rows label-left/value-right), plus the type,
colour and glyph conventions, with AGENTS.md pointing at it for anyone
adding a widget.

1 files changed, 34 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ff8abc9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# Agent notes
+
+Project-level guidance for this repository. The global agent preferences still
+apply; this file only adds what is specific to `conky-theme-udt`.
+
+## Read this first
+
+`DESIGN.md` is the repository's visual identity. Before adding or changing a
+widget, read it and match it: the big value at the card's top-right, rows
+label-left / value-right, one fluid type size, the `ok` / `warning` / `critical`
+colour language. A new card that ignores it is a defect, not a style choice.
+
+## Working on the dashboard
+
+- After editing a widget or `dashboard.lua`: `./restart.sh`. Conky caches a
+  required widget module, so a widget edit needs the restart; editing
+  `dashboard.lua` alone does not.
+- Only a `conky.conf.in` or palette change needs
+  `../unified-desktop-theme/install.sh`, which re-renders `conky.conf`.
+- Checks: `lua test/test_data.lua && lua test/test_layout.lua && lua test/test_weather.lua`
+- Render one widget offscreen without conky:
+  `lua test/render.lua <widget> <cols> <rows> <wspan> <hspan> <out.png>`
+- The offscreen renderer crops to a single card, so it says nothing about size
+  beside neighbours. Check the live dashboard for that.
+
+## Constraints
+
+- This repository is public: no keys, real locations, LAN addresses, hostnames
+  or usernames in committed files. Derive per-host data at runtime; use
+  `Example City` / generic placeholders in fixtures.
+- A Lua error in conky is a blank screen with no message. The `pcall` overlay in
+  `dashboard.lua` is the only reason faults are visible, so parsers and widgets
+  return nil or a safe default rather than raising.
+- Commits are GPG-signed.