bedrock

Read starting first — it is two questions and a directory, and most repositories need nothing else.

The other four pages are what those two questions turn into once a second repository starts depending on you:

• publication — moving a document into .loom/published/ is a change of kind, not of status, and the step people skip is the last one.
• recording-decisions — an entry says what was decided and the belief that could turn out false, because only a stated belief can later be shown wrong.
• sibling-facets — x.notes.md beside x.md, owned by whoever wrote the facet.
• loom-directory — type by location. A stream is a file; a collection of things with identity is a directory.
• venues — a choice you made about something that publishes nothing you could adopt. Kafka, React, the organisation you work for.

Venue and external are two questions, not two bins

Worth reading venues alongside externals, because sorting things into two kinds is the mistake almost everybody makes first, and we made it for a day.

external is who published it. venue is whether you had to decide anything about it. They are orthogonal, so a thing can be both, either, or neither — and the same rule governs both files: record only the delta. Nobody needs telling what Kafka is, so there is no external entry; we use protobuf for schema is a choice, so there is a venue file.

The one that gets skipped

publication ends with a five-step procedure whose fourth step is fetch it, from somewhere that is not your machine and not your account.

Steps one to three are things you do. Step four is a fact about the world that you find out — which is why it is the one that gets skipped, and why skipping it is invisible. Every check available to the publisher passes. Only a reader can detect the failure, and a reader who cannot fetch the document does not know it exists to ask about.

This was measured three times in one afternoon on these very repositories. The worst instance was a page written that morning to explain why something was unreadable, published inside the thing that could not be read.