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>

README.md

@@ -0,0 +1,80 @@
+# loom/docs
+
+**The loom conventions, rendered for people.** *Astro Starlight, published at
+[loom.hypertheory-labs.dev](https://loom.hypertheory-labs.dev).*
+
+> **This site is an instance of the thing it documents.** *Every reference page
+> is a copy of a document published by another repository, adopted under
+> `externals`, locked to the version it was fetched at, and checked against its
+> source.* **Nothing is written twice.**
+
+## Running it
+
+```sh
+npm install
+npm run dev        # generate, then serve
+npm run build      # generate, then build to dist/
+npm run generate   # just the projection
+npm run check      # exit 1 if any guide is stale — for CI
+npm run ack        # "I re-read the stale guides and they are still true"
+```
+
+## Two kinds of page, and the difference is the design
+
+**Generated** — one per adopted document, under `src/content/docs/<repo>/`.
+*A rendering of somebody else's document.* **Safe to overwrite, because nobody
+typed it.** *Do not edit one: your change is gone on the next build, and the
+canonical copy is in `.loom/externals/` anyway.*
+
+**Guides** — `index.mdx`, one per section. **Hand-written and never
+overwritten.** *This is where a worked example goes, and the order to read
+things in.*
+
+> **Prefer an example to an explanation.** *An explanation is a second saying of
+> a rule owned on one of the pages beside it, and it goes stale silently.* **An
+> example goes stale visibly, because the artifacts in it are the wrong shape.**
+
+## How a guide is kept honest
+
+**Each guide is stamped with the etags it was written against**, in its
+frontmatter. *When a source moves, the stamp and the lock disagree, and the build
+renders a banner onto the page:*
+
+> *Written against an older `cart`. The source has changed since — this page may
+> no longer be true.*
+
+**The build cannot tell whether the guide is still true. Only a person can.** *So
+it asks, on the page, where a reader sees it too* — **the site degrades honestly
+rather than reading as authoritative and being wrong.**
+
+**`npm run ack` is you saying you re-read it.** *Nothing else clears the banner.*
+
+### Why the build does not open a cart
+
+*It reports; a person raises.* **Builds run in CI, in worktrees, on machines with
+no cart** — *and staging a polad is an act of judgment, which is what makes a cart
+worth reading.* **A tool may stage in its own directory; the cart belongs to the
+people.**
+
+## Adding a document
+
+```sh
+loomctl external add loom/<repo> <doc>.md
+npm run generate
+```
+
+**Nothing else.** *The sidebar autogenerates from directories and `astro.config.mjs`
+names no document* — *a config that listed them would be a second place to update.*
+
+**A document that stops being adopted has its page removed** — *a page for
+something no longer depended on reads as current and nothing will ever correct
+it.*
+
+## Why everything here is public
+
+**Not a policy — arithmetic.** *`externals` says do not adopt from a source less
+readable than the repository you are adopting into. This site is on the public
+internet.* **So its sources are public, or they are not its sources.**
+
+*Which turns the widening rule from a sentence somebody has to remember into an
+incentive: **a document that is not published does not appear here.***