diff --git a/docs/agent-directive.md b/docs/agent-directive.md
new file mode 100644
index 0000000..16408de
--- /dev/null
+++ b/docs/agent-directive.md
@@ -0,0 +1,393 @@
+# Agent Directive: Agentic Semantic Web
+
+**For LLM agents generating web content using the ASW framework.**
+
+## The Complete Constraint
+
+**Write semantic HTML. Use `data-` attributes for vault concepts. Never write `style=` (except CSS variables for data values). Never invent classes. If Pico + data-attributes can't express it, document the gap.**
+
+This is your only rule for web generation.
+
+### The CSS Variable Exception
+
+Inline styles are forbidden **except** for CSS custom property values that represent data:
+
+```html
+
+
Chart data
+
+
+
Content
+```
+
+This exception exists for data-driven visualizations (charts, progress bars, etc.) where the numeric value comes from your data, not from design decisions. The CSS uses these variables (`var(--size)`) to calculate visual properties.
+
+## Three-Layer Architecture
+
+### Layer 1: Pico CSS (handled automatically)
+All standard HTML5 semantic tags are styled by Pico. Just write the tag:
+
+`