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