primary
The one main action on the screen. Filled and loud so the eye lands on it first.
Avoid: two primaries fighting in one view.
You are reading its output right now. When a loop finishes a job, it does not hand you a wall of notes — it builds a course like this one: one self-contained HTML file, warm and readable, with a dark mode, hand-drawn diagrams, and little things you can click. This lesson opens the engine that makes it, on the very page that engine produced.
Everything in this suite ends the same way. When a loop finishes a job — a bug fixed, a tool built, a topic researched — it does not just say "done" and dump a pile of raw notes on you. It takes what it learned and teaches it back, as a small course you can actually read and click through. The thing that turns a result into that course is called visual-teach. The page you are on right now is one of its lessons.
So this lesson is a little unusual: it explains the very tool that produced it. Look around as you read. The warm paper colour, the moon button in the corner that flips to dark, the hand-drawn diagrams, the "Show the technical detail" panels that open and close, the language switch up top that says EN and PT — every one of those is something visual-teach puts into each lesson on purpose. By the end you will be able to point at any part of this page and say what the engine was doing when it made it.
Why bother turning work into a course at all? Because a result you cannot understand is not really finished. A wall of logs proves the machine did something; it does not help a person get it. visual-teach exists so the human at the end of the run walks away actually understanding what happened — the same way a good teacher does not just hand back a marked exam, they explain it.
One promise sits underneath all of this, and it is worth saying plainly: a visual-teach course is one single file that works on its own. No internet, no install, no server. You can email it, drop it on a USB stick, open it on a plane. Double-click and it just opens. We will see exactly how that is possible in a moment.
Think of it like… a great museum exhibit. Behind the scenes there was months of messy research — digs, arguments, dead ends. But what you walk through is a clean, well-lit room with clear labels, a few things you are invited to touch, and a path that makes sense. visual-teach is the exhibit designer: it takes the mess of a finished job and lays out a room you can actually learn in. Where the analogy breaks: a museum room is fixed in place, while this exhibit is a single file you can carry away in your pocket.
visual-teach is the delivery stage of the loop engineering harness. After a run converges — the scope's measurable "done-when" is met and proven at a real boundary — the loop is required to produce a visual-teach course as the human-readable deliverable. That requirement is the Course Gate: convergence is not "the code passes", it is "the code passes and a self-contained course explaining it exists". The result and the explanation ship together.
Each lesson is a single .html document with inline CSS, inline SVG, and inline JavaScript, and zero external requests — no CDN, no web fonts, no image files, no analytics. The practical payoff is durability: it renders identically from file:// today and in five years, it survives being zipped and emailed, and it cannot break because some remote dependency moved. The course also gets published to a private (secret) gist so it has a shareable URL, but the file itself never depends on that.
Open most web pages and they quietly pull in dozens of other things from the internet — fonts, pictures, code from other companies, trackers. If any of those go missing, the page breaks. A visual-teach lesson refuses to play that game. The words, the colours, the diagrams, and the little interactive bits are all written inside the one file. Nothing is fetched from anywhere.
That choice is the reason this page keeps working no matter where it lands. Wi-Fi off? Still works. Saved it last year? Still works. Sent it to a colleague who opens it on a locked-down work laptop? Still works. The file is the whole exhibit, walls and all — not a ticket that only works if the museum is still standing.
It also keeps things honest. Because nothing loads from outside, the course you receive is exactly the course that was made — it cannot be silently changed after the fact, and there is nothing watching you read it.
Think of it like… a printed pop-up book versus a poster that just says "scan this code to see the pictures." The pop-up book has everything bound into its pages — open it anywhere and it works. The poster is useless the moment the link rots or the signal drops. visual-teach always builds the pop-up book.
<!-- a visual-teach lesson, top to bottom --> <!doctype html> <html lang="en"> <head> <style> /* all the look & feel — inline */ </style> </head> <body> <!-- the words you read --> <svg> <!-- diagrams drawn right here, no image files --> </svg> <script> /* the clickable bits — inline */ </script> </body> </html> # nothing above ever reaches out to the internet.
You do not have to take it on faith. Ask your agent (or do it yourself) to grep the file for the usual ways a page loads something remote — and find nothing:
# run from the course folder; expect NO matches grep -nE 'https?://|src=|@import|cdn|googleapis' lessons/0010-visual-teach.html # the only http(s) you may see are inside SVG xmlns="..." namespaces, # which are identifiers, not network fetches.
Or open the file with your network disconnected, or load it and watch the browser's Network panel stay empty. All three are real boundary checks — exactly the kind of proof the loop demands instead of a claim.
Courses are made to be read, sometimes for a long stretch, so they are dressed in a calm warm-neutral palette: soft ivory paper, ink-dark text, and one friendly clay-orange used sparingly to point at the things that matter. It is meant to feel like a good book, not a dashboard.
And see that moon button at the top right? Press it. The whole page slips into dark mode — easy on the eyes at night — and it remembers your choice next time you open it. If your computer is already set to dark, the lesson quietly starts dark on its own, without a bright flash. You did not configure anything; the engine builds that in.
The point of all this polish is not decoration. A page that is pleasant and readable is a page you will actually finish. Comfort is part of teaching.
Think of it like… a bedside lamp with a dimmer. The same room, the same book — but you can warm the light down for night reading, and the lamp remembers where you left the dial. Nobody should have to re-set the mood every time they pick the book up.
Every colour is a CSS custom property (a "token") on :root — --ivory, --slate, --clay, and so on. Dark mode is a single override block, :root[data-theme="dark"]{…}, that re-points those same tokens to dark values. Because nothing in the lesson hard-codes a hex colour — everything reads a token — flipping one attribute on <html> re-skins the entire page for free. New components inherit dark mode automatically as long as they only use tokens.
A tiny script in the <head> runs before the page paints: it reads the saved choice from localStorage (falling back to the OS prefers-color-scheme) and sets data-theme immediately, so a dark reader never sees a white flash. The toggle button just swaps that attribute and writes the new value back to localStorage. This exact mechanism is part of the shared shell, identical on every lesson.
A course is many lessons, and they must all feel like one thing. visual-teach guarantees that with a clever, almost stubborn rule: every lesson shares one identical shell. The shell is the frame around the content — the colour palette, the top bar with the theme toggle and the EN/PT switch, the little "On this page" menu, the previous/next buttons at the bottom. That frame is written once and then copied, character for character, onto every single lesson.
"Character for character" is not a figure of speech. The shared part of each lesson is required to be byte-identical to a master template. If even one space drifts, an automated check fails and the lesson is sent back. Only the actual teaching — this lesson's words, its diagrams, its demo — is allowed to differ.
The payoff is the feeling you may not even notice: you never have to relearn the furniture. The dark button is always in the same place, the next button always behaves the same way, the menu always looks the same. Your attention stays on the ideas, because the room never rearranges itself between lessons.
Think of it like… a well-run hotel chain. Walk into any branch and the light switch is by the door, the kettle is on the desk, the towels are in the bath. The view out the window changes city to city — that is the lesson content — but the room layout is deliberately the same, so you never fumble for the switch in the dark. The byte-identical rule is the chain's blueprint, enforced to the millimetre.
In the source, the shared region is fenced by comment markers — BEGIN SHARED SHELL / END SHARED SHELL for the CSS, plus the matching fenced blocks for the stepbar, the wiznav, the footer, and the trailing shell <script>. A build builds a lesson by copying the template and editing only outside those fences: the <title>, the step label, the <h1>, and the body between the stepbar and the wiznav. The fenced bytes are never touched.
A verification step extracts the shared region from the lesson and the template and compares them — if the bytes differ, the gate fails and the lesson does not ship. This is a literal example of the loop's Proof Gate applied to the course itself: "shared shell unchanged" is not asserted by the author, it is checked at a real boundary (a byte diff), the same discipline this whole suite runs on.
People arrive at a topic from different places, so every lesson is written in two depths at once. The plain version — the part you are reading — tells the whole story in everyday words, start to finish. You can read only this and walk away genuinely understanding the topic; nothing essential is hidden from you. Then, tucked behind every "Show the technical detail" button, there is a deeper layer with the precise names, the exact commands, the edge cases. Open it if you want it; ignore it if you do not. Either path is complete.
That is the rule the engine enforces: the simple layer must stand on its own. The technical panel adds precision for the curious — it is never where the actual point is kept. You should never have to open a panel just to follow along.
Every lesson also ships in two languages: English and Brazilian Portuguese, side by side, with the EN/PT switch at the top of the page. Only the prose is translated — the commands, file names, and code stay exactly as they are, because those are the same in any language and changing them would break them.
Think of it like… a nature trail with two kinds of signs. The big friendly sign tells you the whole story of the forest in a paragraph anyone can read. Next to it, a small plaque adds the Latin species names and the soil chemistry for the botanists. You get the full walk from the big signs alone — and the trail is posted in both languages so more people can take it.
Formally: the .simple block of every section is required to convey the section's full point without reference to its .technical panel. The toggle uses aria-expanded on the button and an .open class on the panel, and there is an "Expand all technical detail" control for readers who want the dense pass. The .technical layer carries jargon, exact flags, and failure modes — additive precision, never load-bearing meaning.
The PT-BR build is a parallel file under pt/lessons/ with <html lang="pt-BR">, the .cur flipped in the language switch, and relative link depth adjusted. The translation rule is strict: prose only. Code, commands, file paths, and identifiers are copied verbatim — translating grep or a filename would silently break the example. The shared shell stays byte-identical across languages too.
Reading about a thing is one kind of learning; poking it is another. visual-teach builds little interactive bits right into the lesson so you can do the second kind. Here is one, lifted straight from the engine's own demo library — the kind of widget it can drop into any course.
The topic it teaches is small and concrete on purpose: a single button comes in a few variants (bold, quiet, barely-there, danger-red) and a few sizes. The grid below shows every combination as a real, clickable button — not a picture of one. Below the grid, pick a size and watch every example resize at once, and hover a card to see its matching row in the grid light up. This is a demo running live, inside the same single file, with no internet.
Think of it like… a paint store's sample wall, where you can flip the same chip between finishes and sizes instead of squinting at a catalogue. Trying it beats reading about it.
Each row is a variant, each column is a size. Every cell is the real, live .l10cv_btn the demo renders.
| variant \ size | sm | md | lg |
|---|---|---|---|
| primary | |||
| secondary | |||
| ghost | |||
| danger |
The matrix shows what each looks like; these cards say when to reach for each. Pick a size to preview every variant at that size; hover a card to light its row above.
primary
The one main action on the screen. Filled and loud so the eye lands on it first.
Avoid: two primaries fighting in one view.
secondary
The supporting action beside primary — "Cancel", "Back". Outlined, quieter.
Avoid: using it for the action you actually want clicked.
ghost
The low-priority option — "Skip", toolbar icons. Almost invisible until hovered.
Avoid: on a critical or destructive action (too easy to miss).
danger
The destructive action — delete, remove, revoke. Red plus a clear verb plus a confirm step.
Avoid: red alone with vague copy like "OK".
The button takes two orthogonal axes: variant (color/emphasis) and size (padding/font-size). They compose, so a 4×3 grid comes from 4 + 3 = 7 CSS rules, not 12 bespoke buttons. The size picker swaps only the size class on each demo button at runtime — live proof the axes are independent.
/* base + two independent axes (namespaced for this lesson) */ .l10cv_btn { font-weight:600; border-radius:8px; border:1.5px solid transparent; } .l10cv_btn.sm { font-size:13px; padding:7px 13px; } .l10cv_btn.lg { font-size:17px; padding:13px 24px; } .l10cv_btn.primary { background:#D97757; color:#fff; } .l10cv_btn.danger { background:#B04A3F; color:#fff; }
This widget was copied verbatim from the engine's demo exemplar 06-component-variants, then every id, class, and hook was prefixed l10cv_ so it cannot collide with the shared shell or any other demo in the file. Lifting and namespacing is exactly how visual-teach reuses its ~20 demo types across courses without two widgets ever stepping on each other.
A whole course is not written in one heroic burst. It is built the same patient way the loop builds anything: one lesson per pass. The engine learns the topic, drafts a single lesson, checks it, improves it, and only then moves to the next. This very lesson was one such pass. Building incrementally means a problem in one lesson never sinks the whole course.
And a lesson is not "done" just because it exists. Before it ships, it has to clear a short checklist — four plain questions the engine refuses to skip:
Only when all four pass does the lesson count. Stack up enough passing lessons and the course itself crosses the finish line — the moment the loop calls "done" and hands you the result as this course. That hand-off has a name we will meet next: the Publish Gate, where the finished course is put somewhere you can share it.
Think of it like… a chef plating one dish at a time, and a pass kitchen at the end: nothing leaves until it clears the line — right dish, real ingredients, looks the part, ready to serve. Stack up enough plates that pass and the whole banquet is ready.
For the human
The course is your deliverable. It is the readable thing you keep at the end — the part built so a person actually understands what the run did, not just that it finished.
For the model (LLM)
Build incrementally — one lesson per pass — and clear the Mission, Sources, Demo, and Ship gates on each before moving on. No lesson ships on a claim.
For the agent
The course is fully self-contained: it opens from file:// with zero external requests, so it can be verified, zipped, and handed off anywhere without breaking.
Mission gate: the lesson teaches its stated topic with the Simple→Technical pattern and a self-complete simple layer. Sources gate: claims trace to real artifacts or evidence (web facts via the Bright Data CLI, never memory). Demo gate: ≥1 working inline interactive widget and ≥1 inline SVG, zero external resources. Ship gate: opens standalone from file://, shared shell byte-identical to the template, nav and language links correct. A lesson that fails any gate is returned, not shipped.
At the run level, the Course Gate makes a visual-teach course a precondition of convergence: the loop has not delivered until the course exists alongside the proven result. The Publish Gate (next lesson) then publishes that course to a private/secret gist via a flatten-and-rewrite step so it has a shareable URL, while the repo's own course/ remains the canonical home.
None of this is hand-waving — it is real files on disk. A course lives in a folder. There is a master template (the shell every lesson is copied from), a lessons folder with the English files, a parallel pt folder for the Portuguese ones, a demos library the interactive bits are lifted from, an index page that ties the lessons together, and a gallery of the demo types. This lesson is one file in that lessons folder.
You can see all of it. The block below is the actual shape of the course folder that produced this page, and there is a one-liner you can run to list it for yourself.
courses/harness/ ├─ _TEMPLATE-en.html # the byte-identical shell, EN ├─ _TEMPLATE-pt.html # the shell, PT-BR ├─ index.html # course home, ties lessons together ├─ gallery.html # the demo-type gallery ├─ lessons/ │ ├─ 0009-tools.html │ ├─ 0010-visual-teach.html # ← you are here │ └─ 0011-publish.html ├─ pt/lessons/ # parallel PT-BR lessons └─ demos/ └─ 06-component-variants.html # the demo lifted above
# see the whole course tree ls -R courses/harness/ # open this very lesson straight from disk — no server needed open courses/harness/lessons/0010-visual-teach.html
A lesson is produced by copying _TEMPLATE-en.html and editing only the non-shell regions. At convergence, the publish step runs publish-course-gist.js over the course directory — it flattens the tree into unique filenames, rewrites the internal links, and creates a secret gist so the course opens as a navigable bundle. That single outward action is the Publish Gate of the next lesson; the course/ directory in the repo stays the canonical source.
Five quick questions. Pick an answer to see why it is right — retrieval beats re-reading.
Q1What is the deliverable visual-teach produces at the end of a loop run?
Q2Why does a visual-teach lesson keep working with the internet off?
Q3What does the "byte-identical shared shell" rule guarantee?
Q4What must the Simple layer of a section do?
Q5Which gate makes a visual-teach course a precondition of a run being "done"?
Takeaway
visual-teach turns a finished run into a single self-contained HTML course: warm and readable with a dark mode, built on one byte-identical shell, with inline SVG and clickable demos, written Simple→Technical in EN + PT-BR. The human gets a deliverable they actually understand; the model builds it one gate-checked lesson per pass; the agent ships a file that opens anywhere from file://.
grep this file for any https:// fetch and find none, to show you the BEGIN SHARED SHELL markers, or to open the demo at demos/06-component-variants.html. Next, we follow the finished course out the door: The Publish Gate.