# 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.***