jeffryandClaude Opus 5
ebbe3f81d9
A page explaining a private repository, published inside that private repository, is not published. loom-cli's builder measured it: settled, its README, and the page all return 404 anonymously. The publication did not happen, and publication.md says exactly what that means — if nobody can fetch it, nothing happened. The original defect was "the justification for settled is inside settled, which is private". The first fix put a page inside settled. Same repository, same problem, one layer in. The explanation of a thing does not belong inside the thing it explains when the thing is unreadable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.8 KiB
loom
Making things legible between a person and an agent, across repositories and across time.
Most of what an agent needs to know is not in the code it is looking at. It is in another repository, or in a cluster, or in how the two of you have agreed to work. These are the conventions for writing that down where it can be found, and for finding out when it changes.
Start with the question, not the repository
| if you are asking | go to |
|---|---|
"what is this .loom directory?" |
bedrock |
| "how do I set this up in a repository?" | bedrock → starting |
| "how do I depend on somebody's document and know when it changes?" | externals |
| "how do we work something out before one of us changes it?" | cart |
| "how do I mark up your file without editing it?" | annotating |
| "why is it like this?" | settled — private, what it is — and every repository's own .loom/event-log.md |
And if you want an example rather than a description:
jeffry/homelab-cluster
— six documents and one gap, written for somebody who has to decide something.
What each one is
bedrock — the primitives.
What a .loom directory is, how a facet sits beside a file, what an entry says,
what publishing means. Most repositories never need to read it; its audience
is people building conventions rather than using them.
externals — how a repository records what it depends on. Pull a copy, keep your usages and gaps beside it, reconcile when it changes.
cart — a bounded round between two parties, which starts, runs, converts, and is gone. For when neither of you knows yet.
annotating — how two parties mark up each other's files without either of them diffing anything. Everything else here rests on it.
registry — not built. A service that would aggregate gaps across
repositories and explain itself to somebody arriving cold. Everything else
works without it, deliberately.
settled — private. Decisions about the shape of all this.
This index says what each thing is for. It does not list what is in this organisation — the platform already answers that, and a hand-written list would be a claim of completeness that goes wrong the first time somebody adds a repository. A repository with no line here is unannotated, not excluded.