How it fits together
This section explains less than any other section on this site, and that is deliberate.
Loom's reasoning is already written down twice, in two places built for two different jobs. There is a course, which teaches the ideas and is meant to be worked through rather than read. And there is a record of every ruling that was made, written on the day it was made, saying what was rejected as well as what was chosen.
Copying either onto a page here would make a third version to keep true — and the copy on a documentation site is the one that goes stale, because nothing breaks when it does. So this page is a map. Eight ideas, a paragraph each, and two doors out of every one of them.
The bargain, in one paragraph
Loom lets an AI change a running interface, and the reason that is not terrifying is that it can only say a small number of things. A page is data, a change is data, and the words a change may use are a list you wrote. You give up the freedom to have the AI produce anything at all, and what you get back is a change you can read, measure, refuse and undo. Every idea below is a consequence of that trade.
The other half of the same bargain: behavior lives in the component you registered, not in the tree. The tree says a checkout goes here. What a checkout does is yours, and no proposal can reach it.
The two doors
Under each idea are two links, and they go to different kinds of place.
Work through it goes to a lesson. The course is built on the finding that rereading a clear explanation feels like learning and mostly is not, so a lesson asks you to answer before it explains and to recall before it moves on. It is slower than reading this page on purpose. Do not treat it as a longer version of the paragraph above it.
It also runs in order. A lesson opens with a closed-book warm-up on the lessons before it, and the explanation is behind that — so arriving at lesson nine straight from this page is the long way round, and the course is better started at the beginning. If what you want is the argument rather than the practice, take the other door.
The ruling goes to a decision record: what was decided, when, what it costs, and — the part you cannot reconstruct later — which reasonable alternative was turned down and why.
One of those two stays here and one does not, and it is worth knowing which before you click. A lesson is a page on this site, with the course's own machinery around it. A ruling is a file in the repository — a working note, written on the day, in the project's own shorthand — so it is marked ↗ wherever this section links one. Nothing opens in a new tab; the back button brings you straight back.
The eight ideas
A page is data, not code
Open a Loom page and there is no markup and no JavaScript in it — there is a tree of ordinary data. A heading, the words inside it, the box it sits in: each is a node with a name, a few settings and a list of children. That matters because data can be printed, compared, stored and handed back an hour later, and a function cannot.
Work through it
A change is data too
Nothing edits a page in place. A change arrives first as a written plan — add this node here, replace that setting, move this one, remove that one — and there are only those four kinds of operation, ever. So you can read what is about to happen to the page before any of it has happened.
Work through it
Every node keeps its name
A card moves from third in a list to first. It is the same card, so it keeps the same id, and where it sits is worked out from the tree rather than used to say which node it is. This is the small thing that makes “change that one” still mean something after five other changes have landed.
Work through it
Nothing throws at a seam
Hand a component something it does not understand and it does not take the page down. It renders what it can and leaves a note behind saying what was wrong and where. Time works the same way — the clock is passed in rather than read — so the same inputs give the same page, which is what makes a record of what happened worth keeping.
Work through it
Undo is another change
Putting something back is not a rewind to a saved copy. The runtime works out the exact change that would reverse this one — put back what was removed, remove what was added — and then proposes it like any other change. Which means an undo can be refused, and means it shows up in the record as a thing somebody did.
Work through it
The ruling
Two questions, then three answers
Before anything is applied, the runtime asks two things about the change: how much is at stake if it is wrong, and could it be undone. Then it says one of three words — yes, ask a person, or no. The middle answer is the point. Software that can only permit or forbid has to decide at build time which changes are safe, and it will be wrong, because that depends on what the change touches.
Work through it
The model is never shown the tree
The AI is not handed the page's data structure and asked to edit it. It is shown a simplified picture of the page, and it answers in a deliberately small grammar with room for very little. A narrow reply is not a limitation to work around; it is what stops a wrong answer from being an inventive one. The runtime translates in both directions.
Work through it
The vocabulary is a list you write
A proposal may only name things you have registered — your heading, your card, your checkout. Anything else is not a bug that shows up when the page renders; it is a change that could not be proposed. This is the bargain the whole framework rests on: a bounded vocabulary buys you a change you can review, and the behavior lives in your component rather than in the tree.
Work through it
The lessons are meant to be worked through rather than read, and the course keeps track of what is due — start it here.
Everything else that has been decided
The eight above are the spine. There are far more rulings than that — on how identity survives a restart, on what telemetry may keep, on what a primitive is allowed to name — and they are all in one list.
Decision records is that list, with a note on what it means when one of them has been replaced.