loom/docs

Files

T

jeffryandClaude Opus 5 969524b8ea the loom conventions, rendered — and adopted the way the conventions say

Astro Starlight over .loom/externals/. Every reference page is a copy of a
document published by another loom repository, adopted with loomctl, locked to
the etag it was fetched at. Nothing is written twice.

Two kinds of page. Generated ones are overwritten every build because nobody
typed them. Guides are hand-written, never overwritten, and stamped in
frontmatter with the etags they were written against; when a source moves, the
build renders a banner onto the page asking whether it is still true. It cannot
answer that — only a person can — so it asks where a reader will see it too, and
the site degrades honestly instead of reading as authoritative and being wrong.
npm run ack is the person saying they re-read it.

Declined: having the build stage a polad into the cart. loomctl external check
does that and is right to, but a docs build runs in CI and in worktrees where
there is no cart, and staging a polad is an act of judgment. The build reports;
a person raises.

The guides are worked examples rather than explanations, deliberately. An
explanation is a second saying of a rule owned on the page beside it and goes
stale silently; an example goes stale visibly, because the artifacts in it are
the wrong shape.

Generation is byte-deterministic — locks are walked in path order, no timestamps
— because the diff is most of the value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-08 09:51:16 -04:00

3.0 KiB

Raw Blame History

Publication

What a repository has handed over for others to depend on lives in .loom/published/.

Publishing is a change of kind, not a change of status. An unpublished document is an implementation detail you may rename at will. A published one is a contract.

So publication is an act somebody performs — a file moves in — and the move is a diff that shows up in review. A flag in frontmatter is a line nobody notices; this is the moment a thing becomes somebody else's problem, and it should be unmissable.

ls .loom/published/ is what have we committed to? — and it is the question to ask before changing anything.

Publishing is not an act you can complete alone

A file in .loom/published/ that its intended readers cannot fetch is not published. The move is the act, but the act is not finished until somebody who is not you can perform the read.

The failure is invisible from the inside. Every check available to the publisher passes — the file is there, the commit landed, the path is right. Only a reader can detect it, and a reader who cannot fetch it does not know the document exists to ask about.

The commonest form is a document that answers "why can you not see this?" and is published inside the thing that cannot be seen.

So publication has a visibility, and it is a property of the act rather than of the file. "Others" is not "everyone". Naming who the readers are is part of publishing, because a repository that depends on this one has to know whether it is inside that set — and because a reader who copies a document out inherits the copy without inheriting the visibility it was published under.

The test is a fetch you did not perform.

Doing it

Decide it is a contract and not a detail. This is the whole decision and the rest is mechanics.
Move the file into .loom/published/. One commit, so the diff carries it.
Say who the readers are — if it is not obvious from where it landed.
Fetch it. From somewhere that is not your machine and not your account.
Record the decision, if you keep a log.

Step 4 is the one that gets skipped and the only one that can fail. Steps 1 to 3 are things you do; step 4 is a fact about the world that you find out.

Then say what it depends on. A published document that quietly requires a private one has moved the problem rather than solved it.

What is published is a document

Prose, in whatever form its readers need. If a repository organises its thinking some other way internally, that is its own business: a consumer cannot tell whether it did, and must not need to.

What is not exported is not hidden. The rest of the repository is there to read. It is simply not what you depend on.

There is no directory for what is unpublished

Everything else is simply elsewhere in the repository. Naming the complement invents a category — and a directory called internal/ would look like a security boundary and not be one.

3.0 KiB Raw Blame History