the org index

Routes by question rather than by repository — what is this .loom directory, how
do I set it up, how do I depend on somebody's document, how do we work something
out, how do I mark up your file. A newcomer has a question, not a repository
name, and a list of moves can be used before it is understood where an inventory
must be read first.

Points at jeffry/homelab-cluster for anyone who would rather see one than read
about it.

Says what each repository is for and does not list what is in the organisation:
the platform already answers that, and a hand-written list is a claim of
completeness that goes wrong the first time somebody adds a repository. A
repository with no line here is unannotated rather than excluded.

Names registry as not built and settled as private, so neither reads as a
dangling reference.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,58 @@
+# loom
+
+**Making things legible between a person and an agent, across repositories and
+across time.**
+
+*Most of what an agent needs to know is not in the code it is looking at. It is
+in another repository, or in a cluster, or in how the two of you have agreed to
+work. **These are the conventions for writing that down where it can be found,
+and for finding out when it changes.***
+
+---
+
+## Start with the question, not the repository
+
+| if you are asking | go to |
+|---|---|
+| **"what is this `.loom` directory?"** | [bedrock](https://git.hypertheory-labs.dev/loom/bedrock) |
+| **"how do I set this up in a repository?"** | [bedrock](https://git.hypertheory-labs.dev/loom/bedrock) → *starting* |
+| **"how do I depend on somebody's document and know when it changes?"** | [externals](https://git.hypertheory-labs.dev/loom/externals) |
+| **"how do we work something out before one of us changes it?"** | [cart](https://git.hypertheory-labs.dev/loom/cart) |
+| **"how do I mark up your file without editing it?"** | [annotating](https://git.hypertheory-labs.dev/loom/annotating) |
+| **"why is it like this?"** | *`settled` — **private***, and every repository's own `.loom/event-log.md` |
+
+**And if you want an example rather than a description:**
+**[`jeffry/homelab-cluster`](https://git.hypertheory-labs.dev/jeffry/homelab-cluster)**
+— *six documents and one gap, written for somebody who has to decide something.*
+
+## What each one is
+
+**[bedrock](https://git.hypertheory-labs.dev/loom/bedrock)** — the primitives.
+*What a `.loom` directory is, how a facet sits beside a file, what an entry says,
+what publishing means.* **Most repositories never need to read it**; its audience
+is people building conventions rather than using them.
+
+**[externals](https://git.hypertheory-labs.dev/loom/externals)** — how a
+repository records what it depends on. *Pull a copy, keep your usages and gaps
+beside it, reconcile when it changes.*
+
+**[cart](https://git.hypertheory-labs.dev/loom/cart)** — a bounded round between
+two parties, which starts, runs, converts, and is gone. *For when neither of you
+knows yet.*
+
+**[annotating](https://git.hypertheory-labs.dev/loom/annotating)** — how two
+parties mark up each other's files without either of them diffing anything.
+**Everything else here rests on it.**
+
+**`registry`** — *not built.* **A service that would aggregate gaps across
+repositories and explain itself to somebody arriving cold.** *Everything else
+works without it, deliberately.*
+
+**`settled`** — *private.* Decisions about the shape of all this.
+
+---
+
+*This index says what each thing is **for**. It does not list what is in this
+organisation — **the platform already answers that**, and a hand-written list
+would be a claim of completeness that goes wrong the first time somebody adds a
+repository. **A repository with no line here is unannotated, not excluded.***