From 5bfec6a48aba6193b1e2aa337d161a83698ec813 Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Mon, 7 Sep 2026 11:40:01 -0400 Subject: [PATCH] the org index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e931e8f --- /dev/null +++ b/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.***