jeffryandClaude Opus 5
969524b8ea
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>
6.0 KiB
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
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.