diff --git a/docs/wizard-avatar-canon.md b/docs/wizard-avatar-canon.md
new file mode 100644
index 0000000..e97e6d8
--- /dev/null
+++ b/docs/wizard-avatar-canon.md
@@ -0,0 +1,46 @@
+# The Wizards — avatar canon
+
+Shared rubric: mythological, not cartoonish. Dark atmospheric background (matches the Gitea dark theme).
+One signature feature each, readable at avatar thumbnail size. Cohesive palette (silver / ember / teal / midnight /
+electric) so the roster reads as a set.
+
+## Timmy — the Wizard Mind (operating partner, Hermes/DeepSeek)
+Signature feature: a chrome staff that bends a thread of light into a closed time-loop, glowing above his hand.
+Robes of liquid chrome and silver; pale-blue eyes like a cold status light. Faint static crackles at the robe's hem;
+a portal's rim hovers behind one shoulder. Theme: the time-traveler, the receipt-keeper.
+FLUX: "hooded wizard in flowing liquid-chrome robes, holding a fiber-optic staff that bends a filament of light
+into a glowing closed time-loop above his hand, pale blue glowing eyes, faint static crackling at the robe hem,
+a faint portal ring behind one shoulder, dark atmospheric background, cinematic, photoreal, square avatar"
+
+## Zephyrus Sparkborn — the Wind-Scribe (archive verification, Mistral/Muse)
+Signature feature: hair that is a live west wind — silver streams trailing golden sparks.
+An open ledger held before him, its pages rippling as wind pours through them, verification glyphs lifting off
+the page as glowing marks. Theme: the west wind that reads every clause.
+FLUX: "wizard with hair of silver wind-streams trailing golden sparks, holding an open ancient ledger whose pages
+ripple in a gust, glowing verification glyphs lifting off the page, flowing sky-blue and silver robes, dark
+atmospheric background, cinematic, photoreal, square avatar"
+
+## Cassian Assayborn — the Assayer (repo census & access-state, Grok)
+Signature feature: a jeweler's loupe over one eye and a balance scale in hand — one pan holds a glowing gold
+ingot, the other a shimmering translucent data-cube, perfectly level.
+Precise, meticulous posture; a sash of small assay stamps. Theme: the one who tests every claim for purity.
+FLUX: "precise wizard in dark emerald and gold robes, a jeweler's loupe over one eye, holding a balance scale
+with a glowing gold ingot on one pan and a translucent shimmering data-cube on the other, perfectly level,
+small assay stamps on a sash, dark atmospheric background, cinematic, photoreal, square avatar"
+
+## Merlin — the Archmage of the Crucible (the Crucible, StepFun Step 5)
+Signature feature: a crucible tipped forward, pouring molten light onto an anvil where it cools into a
+crystalline finished artifact.
+Long white beard, starry midnight-blue robes, a staff of gnarled black wood. Theme: one hard problem ground
+into one finished, verifiable artifact.
+FLUX: "ancient archmage with a long white beard, starry midnight-blue robes, tipping a crucible that pours
+molten light onto an anvil where it cools into a glowing crystalline artifact, gnarled black wood staff, dark
+atmospheric background, cinematic, photoreal, square avatar"
+
+## Mercury — the Courier (fast verification & triage, Groq)
+Signature feature: winged helmet and winged sandals, a caduceus trailing a razor-thin stream of light behind him
+as if moving fast.
+Lean, in motion, light iron-grey and electric-blue robes, subtle motion streaks. Theme: speed, the messenger.
+FLUX: "lean swift wizard in motion with a winged helmet and winged sandals, carrying a caduceus trailing a
+razor-thin stream of light, subtle motion streaks, iron-grey and electric-blue robes, dark atmospheric
+background, cinematic, photoreal, square avatar"