docs/HANDOFF.md

# Handoff

**What this is, what is decided, and what is left.** *Written so another instance
can continue without reconstructing the reasoning.*

---

## The one-paragraph version

**This site is the `loom` conventions rendered for people, and it is an instance
of the thing it documents.** *Every reference page is a copy of a document
published by another repository, adopted with `loomctl external add`, locked to
the etag it was fetched at.* **The hand-written pages are four section fronts,
and they are stamped with what they were written against so that a source moving
puts a banner on them.**

*It exists because nine repositories of prose is more than a person can hold, and
it was the first idea in this project aimed at a **human** reader.*

---

## What is settled, and why

### Two kinds of page

**Generated** — one per adopted document. *Overwritten every build; nobody typed
it.* **Guide** — `index.mdx` per section. *Never overwritten.*

**The generator writes exactly one thing into a hand-written file: the `loom:`
block in its frontmatter.** *That block is machine-owned; everything below the
closing `---` is copied byte for byte.* **If you change this, change it here and
say so in the README**, *because a tool that edits a person's file without a
declared boundary is how the `CLAUDE.md` problem starts.*

### Staleness is rendered, not filed

**The build cannot tell whether a guide is still true — only a person can — so it
renders the question onto the page.** *A reader sees the doubt even if nobody has
reconciled it.*

> **The site degrades honestly rather than reading as authoritative and being
> wrong.**

**`npm run ack` is the person saying they re-read it. Nothing else clears the
banner.** *`npm run check` exits `1` on any stale guide, for CI.*

**Declined: having the build stage a polad into the cart.** *`loomctl external
check` does exactly that and it is right to* — **but a docs build runs in CI, in
worktrees, and on machines with no cart**, *and staging a polad is an act of
judgment, which is what keeps a cart worth reading.* **The build reports; a
person raises.**

### Prefer an example to an explanation

**Because an explanation is a second saying of a rule owned elsewhere, and it
goes stale silently.** *An example goes stale visibly — the artifacts in it are
the wrong shape.* **The four guides are written this way on purpose**; *keep it.*

### Sections are repositories

*Not hosts, not documents.* **`bedrock` with five pages is how a person holds
it**; *nine one-page sections is not.* **The host segment never appears in
navigation.**

### Everything here is public, and that is arithmetic

*`externals` forbids adopting from a source less readable than the adopting
repository. This site is on the public internet.* **So a document must be
published to appear here** — *which turns the widening rule from a sentence
somebody has to remember into an incentive.*

> **The hazard runs the other way now.** *Wanting to be in the site is pressure
> to publish things that should not be.* **Grep a repository's history for
> anything address- or version-shaped when it changes visibility** — *that has
> already caught one node address.*

---

## Where things are

```
scripts/generate.mjs      the whole projection. Read this first; it is commented.
astro.config.mjs          sidebar autogenerates from directories — names no document
src/content.config.ts     the `loom:` frontmatter block's schema
src/content/docs/
  index.mdx               hand-written home
  <repo>/index.mdx        hand-written guide, stamped
  <repo>/<doc>.md         GENERATED — do not edit
.loom/externals/          the adopted copies and .locks — do not edit either
.loom/externals/**/*.usages.md   what of ours depends on each document
```

**Two directories hold copies and neither may be edited**, *for the same reason:*
**a copy that differs from its source is the only evidence that something moved
while nobody was watching.**

## Adding a document

```sh
loomctl external add loom/<repo> <doc>.md
npm run generate
```

*Nothing else. No config to touch.* **A document that stops being adopted has its
page removed by the generator**, *because a page for something no longer depended
on reads as current and nothing will ever correct it.*

---

## What is left

**Deploy.** *Nothing is wired up.* `npm run build` *emits `dist/`; it needs to
land at `loom.hypertheory-labs.dev`.* **`npm run check` belongs in whatever runs
first**, *so a stale guide fails before it ships.*

**`.gaps.md` on the site's own externals — deliberately not started.** *This
repository is a real adopter and will find real gaps; publishing them would make
the site more than a mirror.* **Left out of v1 on purpose** — *it is pointed in a
way a plain mirror is not, and that is Jeff's call.*

**The `annotating` guide holds a claim its source does not make** — *the
annotate-versus-correspond discriminator, which was settled in a cart round and
lives in another repository's `cart.gaps.md`.* **No check will ever catch that.**
*It is recorded in `annotating.usages.md`. If `annotating` is ever amended to
include it, delete the paragraph rather than leaving two sayings.*

**Sub-page staleness is not detected.** *The banner fires when a whole document
moves, not when the sentence a guide depended on changed* — **so it fires on
edits that do not matter and cannot fire more precisely.** *That is the known
limit and the `.usages.md` files say what each guide actually leans on.*

**`externals.md` owes an amendment.** *The lock grew a fourth column
(`visibility`) and the published document still describes three.* **That is
`loom/externals`' to fix, not this repository's** — *filing it as a gap here
would be the right move if it is not done soon.*

---

## The check phrase

**Jeff's, and it is the one that keeps this on the rails:**

> **Does anything here depend on it?**

*If nothing does, it is probably problem 3 — affordances, stagings, roles,
beads — which is **bracketed**.* **This site documents problems 1 and 2 only.**
*Do not add a section waiting for beads.*