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>

.loom/README.md

@@ -0,0 +1,15 @@
+# `.loom` — loom/docs
+
+**This repository publishes nothing.** *It is a reader.*
+
+**What is here is `externals/`** — a copy of every document the `loom`
+organisation publishes, locked to the version it was fetched at. *The site at
+[loom.hypertheory-labs.dev](https://loom.hypertheory-labs.dev) is those copies,
+rendered, plus four hand-written section fronts.*
+
+**Nothing in `externals/` is edited here.** *A copy that differs from its source
+is the only evidence that something moved while nobody was watching, so editing
+one destroys the mechanism this repository exists to demonstrate.*
+
+*What we hold about a document goes in a facet beside it — `.usages.md` for what
+of ours depends on it, `.gaps.md` for what we expected and did not find.*