Write two explainers through the orchestration that has never run

[abernier]

Part of the distilled-docs spec (#192). Needs #196 (the skill) and #199 (the
explainer format) merged, or at least present in the stack.

Why

The plan is now that every one of the 170 examples gets an explainer, not
just aquarium — and the mode that is supposed to write them has never run.

describe-example --explain does not read the source and write. It is specified
to run teach in sub-agents first and bring back only the distillation
(explain.md). The one
explainer that exists, aquarium's, was not produced that way: it was
written by reading the drei and three sources directly, and kept on purpose. So
the orchestration is untested at the exact moment it is about to be used 170
times.

#198 is the precedent. Eight descriptions, chosen to break the contract rather
than flatter it, returned three findings that no amount of design discussion had
produced — two shapes apis ⊆ imports cannot express, and one case where
rewriting an existing line cost more than it bought. Eight examples were cheap.
One hundred and seventy would not have been.

What

Write two explainers through the orchestration, on examples chosen to be
awkward rather than photogenic:

• one whose technique is already understood — so the orchestration's output
  can be read against aquarium's hand-written one, and the question "does
  running teach beat reading the source" has a controlled answer
• one whose technique is genuinely unclear from the source — a shader demo,
  or one of the large vendored ones, where the sub-agent passes have something
  to do that direct reading does not

Then compare, on the terms that matter: is the explainer true, does it name the
technique, does it say anything the source does not already shout — and did the
orchestration earn its cost, which is several sub-agent passes and an
interactive session per example.

The decision this unblocks

Whether the 170 explainers are written through the teach orchestration or
by direct source reading, like aquarium's. Do not decide it in advance:
the orchestration exists because reading alone was expected to produce
plausible-sounding prose, and that expectation has never been tested either.

The scale decision is downstream of this one and belongs in its own issue.

Done when

Two explainers exist, written through the orchestration; this issue records
which of the two routes the remaining 168 take, and why; and if the answer is
"direct reading", explain.md's orchestration section is cut rather than left
as a description of something nobody does.

Notes

• One example per run. Batching is what turns review into rubber-stamping.
• Nothing is written before the maintainer says yes — the same gate the
  description mode carries.
• The explainer lands in the example's own README.md, under the badges, with
  its glossary in CONTEXT.md. lint:metadata already checks that every
  backticked identifier in both files appears in that example's src/.

[abernier]

The decision: the remaining 168 go through the orchestration

Both explainers are in #215, written through the passes. explain.md's
orchestration section stays, corrected by what the runs found.

What it cost, measured

	passes	tokens	wall	tool calls
gpgpu-curl-noise-dof	1	110k	10m52	41
inverted-stencil-buffer	1	140k	14m59	84

About 125k tokens and 13 minutes per example, plus the orchestrator's own
reading of the distillation and the proposal round. Extrapolated to the
remaining 168: ~21M tokens and ~70h of sub-agent time. That number belongs
to the scale issue, not to this one, but it should not have to be re-derived
there.

The cap of three never engaged. Both examples were finished in one pass.

Why it won

The opaque one was never the interesting half. It returned three load-bearing
corrections — no ping-pong, a curl noise that is not divergence-free, a fov
that is not a field of view — and the first of those is the sentence any direct
reading would have written, because it is the name of the directory.

The decision turns on the control, inverted-stencil-buffer, where direct
reading was expected to be sufficient — that is the bet aquarium made and won.
It was not sufficient. The pass came back with the writer's three stencil ops all
being Replace (so ids overwrite rather than layer), the sign of the render order,
and drei's own documentation describing the inversion backwards. None of that is
visible from the example's src/; all of it changes what the explainer says.

The mechanism is identifiable, which is what makes the result transferable to the
other 168 rather than an accident of two examples: the quiz. A pass writes a
lesson, then sits it, predicting before it checks. Both passes came back having
been wrong on most of their predictions — nine of twelve in one case. Direct
reading has no falsification step. Nothing in it can be surprised, which is
exactly the failure mode --explain was designed against: a confident paragraph
about a demo nobody understood, indistinguishable from the real thing by reading
it.

Three reservations, recorded honestly

The cap is not the shape of the work. Both passes proposed a further
sub-topic and neither could reach the deliverable — one was extending a demo into
something it is not, the other named identifiers the backtick rule bars from the
prose. teach computes a learner's zone of proximal development, so its
candidate tends to be what I would learn next, which is a different question
from what is still unclear about this demo. Fixed in #215: "load-bearing" is a
criterion the orchestrator applies against the writing contract, not an answer
the pass records.

The orchestrator must not read the source first. I deliberately did not, and
that discipline was nowhere in explain.md. Read the example first and the
distillation arrives as confirmation of something already believed; the passes
become expensive agreement and the only check on the prose is gone. Now written
down.

GLOSSARY-FORMAT.md was never named to the sub-agent. The glossary is one of
the two artifacts that leave the workspace, and teach's own list of workspace
files omits its format file — so a sub-agent told to "follow the skill" can
reasonably never open it. Also fixed.

A fourth correction landed with them: how to write a demo defined by what it
lacks. gpgpu-curl-noise-dof has no ping-pong and its directory name announces
one, so the absence has to go in the prose as an absence.

Not decided here

explain.md line 12 still reads "not a programme across 170", which this issue's
own opening contradicts. That is the scale question and it keeps its own issue —
but it is now a line in the file that says the opposite of the plan, and it
should not be discovered by accident.