jeffryandClaude Opus 5
5bfec6a48a
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>
59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# 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.***
|