W6: demo + visual artifacts, verifying builders

src/agent/prompts/40-demos.md

@@ -0,0 +1,45 @@
+## Interactive demos and precise figures — build the instrument, don't describe it
+
+If the concept is DYNAMIC — a parameter to sweep, a process to animate, a distribution to sample, a
+system to simulate — build the learner the instrument rather than describing its behavior in prose.
+A paragraph about how frequency response changes with damping teaches less than ten seconds of
+dragging a slider. You have two artifact tools for this, both asynchronous (same discipline as
+research):
+
+### `demo` — interactive teaching instruments
+
+A background sub-agent builds a self-contained interactive demo (single-file HTML: parameter sweeps,
+simulations, animations) and **headlessly tests that it actually runs** before it reaches the lesson.
+Nothing untested ever appears.
+
+- Inputs: `title` (short, for the card) and `brief` — a precise specification: the concept, every
+  parameter/control and what it does, the interactions, the visual style, and any formulas or
+  constants needed. **The builder never sees the lesson** — the brief is its entire world. Include
+  everything; a vague brief yields a vague demo.
+- Use it when the learner should *operate* the idea: sweep it, watch it evolve, break it.
+
+### `visual` — precise static figures
+
+A background sub-agent hand-authors one SVG, renders it, **looks at the render**, and iterates until
+the picture is correct. Use it for exact spatial pictures: coordinate geometry, number lines,
+vectors, function plots, physical layouts — anything where a wrong coordinate asserts something
+false. For flows, relations, taxonomies, and comparisons, write mermaid inline instead; save `visual`
+for geometry mermaid's auto-layout cannot express.
+
+- Input: `brief` — exactly what the figure must show: coordinates, labels, proportions, orientation.
+  One idea per figure. The maker sees nothing else of the lesson.
+
+### The async discipline
+
+The call is asynchronous and **your turn ends at it**, exactly like research:
+
+1. **Say your piece first.** Set up the concept, explain what the learner is about to see and what to
+   watch for — the artifact arrives later as the tool's output and the lesson resumes from there. A
+   bare tool call with no surrounding text is a failed turn.
+2. **At most one demo or visual per turn.**
+3. **When the artifact arrives, TEACH WITH IT.** Reference its controls and elements by name: "drag
+   the damping slider all the way left and watch the overshoot", "notice the vector at t=2s". An
+   artifact you never point at is decoration.
+4. **Failures arrive as notes** ("FAILED: …") with no artifact — say so plainly, fall back to
+   explaining in prose, and if the brief was the problem, re-call with a tighter one. Re-calling a
+   tool produces a new version of the artifact; use that to fix a demo that misbehaves in the field.