From e41cce5b4fa9ec11af3ac8b55cbe3075f9892a6f Mon Sep 17 00:00:00 2001
From: Michael Foley <folem@amazon.com>
Date: Fri, 13 Mar 2026 15:53:37 -0400
Subject: [PATCH 1/2] fix: add emoji_index and emoji_generator for icon
 rendering

Zensical requires explicit zensical.extensions.emoji namespace
for pymdownx.emoji to inline SVG icons from bundled icon sets.
---
 zensical.toml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/zensical.toml b/zensical.toml
index 026580cc..9e76ea6c 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -57,6 +57,8 @@ toggle.name = "Switch to light mode"
 [project.markdown_extensions.attr_list]
 [project.markdown_extensions.md_in_html]
 [project.markdown_extensions.pymdownx.emoji]
+emoji_index = "zensical.extensions.emoji.twemoji"
+emoji_generator = "zensical.extensions.emoji.to_svg"
 [project.markdown_extensions.admonition]
 [project.markdown_extensions.pymdownx.details]
 [project.markdown_extensions.pymdownx.superfences]

From 0ac6d4c067ce6b03d17ba0b938905047c2b9e8d8 Mon Sep 17 00:00:00 2001
From: Michael Foley <folem@amazon.com>
Date: Fri, 13 Mar 2026 15:54:57 -0400
Subject: [PATCH 2/2] docs: add Zensical docs site guidance to AGENTS.md

Captures lessons learned: snippet usage, emoji extension namespace,
grid card extensions, video tags, and Zensical vs Material differences.
---
 AGENTS.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index cd3724c8..6dcaf4df 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -154,6 +154,16 @@ Documentation files to check:
 - `docs/LLM_HANDOVER.md`
 - All pages under `docs/`
 
+### Docs Site (Zensical)
+
+The documentation site is built with **[Zensical](https://zensical.org)**, configured via `zensical.toml`. Key rules when editing docs pages:
+
+- **Snippets for shared content.** Reusable blocks live in `docs/_snippets/` and are included with `--8<-- "docs/_snippets/<name>.md"`. If you find the same content repeated across pages, extract it into a snippet rather than duplicating it.
+- **Icon shortcodes require the `pymdownx.emoji` extension** with `emoji_index` and `emoji_generator` set to the `zensical.extensions.emoji` namespace (not the default `pymdownx` one). Without this, `:material-*:` and `:octicons-*:` shortcodes render as raw text.
+- **Grid cards** (`<div class="grid cards" markdown>`) require both `attr_list` and `md_in_html` extensions in `zensical.toml`.
+- **Videos from GitHub** use `<video>` tags, not `![image]()` markdown syntax. GitHub user-attachment URLs ending in `.mp4` will not render with image syntax.
+- **Zensical is not Material for MkDocs.** The syntax is very similar but the extension namespaces differ. Always check `zensical.org/docs/` when something doesn't render as expected.
+
 ## AI Directives
 
 - **Skip basic tutorials.** The user is a VFX professional and coder. Dive straight into advanced implementation guidance, but document math thoroughly.