From 79473f582ab362f7d4934be4dc07076068b31ad8 Mon Sep 17 00:00:00 2001
From: Eric Liu <eric@ericxliu.me>
Date: Sat, 20 Dec 2025 20:41:56 -0600
Subject: [PATCH] docs: add Hugo partials structure documentation

---
 AGENTS.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a44ed9c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# Hugo Partials Structure
+
+This site uses the **hugo-coder** theme with the **hugo-cloak-email** plugin.
+
+## Partial Directories
+
+### `layouts/partials/`
+Standard Hugo partial override directory. Files here override theme partials when called via `partial "name.html"`.
+
+**Used for:**
+- `cloakemail.html` — Overrides hugo-cloak-email's default partial
+- `head.html` — Adds font preloading and AdSense
+- `footer.html` — Custom footer with `[commit]` placeholder
+- `home/social.html` — Integrates cloakemail for email obfuscation
+- `home/avatar.html` — Custom avatar rendering
+
+### `layouts/_partials/`
+Non-standard directory used by **hugo-coder** theme. Files here override theme partials when called via `partial "_partials/name.html"`.
+
+**Used for:**
+- `csp.html` — Custom Content Security Policy with additional script sources
+
+## How Hugo Resolves Partials
+
+Hugo's lookup order tries user overrides first, then falls back to theme files:
+
+1. `layouts/partials/` or `layouts/_partials/` (your overrides)
+2. `themes/<theme>/layouts/partials/` or `themes/<theme>/layouts/_partials/`
+
+## Verification
+
+Run `hugo --templateMetrics` to see which templates are actually being used and their execution counts.