jeffryandClaude Opus 5
969524b8ea
Astro Starlight over .loom/externals/. Every reference page is a copy of a document published by another loom repository, adopted with loomctl, locked to the etag it was fetched at. Nothing is written twice. Two kinds of page. Generated ones are overwritten every build because nobody typed them. Guides are hand-written, never overwritten, and stamped in frontmatter with the etags they were written against; when a source moves, the build renders a banner onto the page asking whether it is still true. It cannot answer that — only a person can — so it asks where a reader will see it too, and the site degrades honestly instead of reading as authoritative and being wrong. npm run ack is the person saying they re-read it. Declined: having the build stage a polad into the cart. loomctl external check does that and is right to, but a docs build runs in CI and in worktrees where there is no cart, and staging a polad is an act of judgment. The build reports; a person raises. The guides are worked examples rather than explanations, deliberately. An explanation is a second saying of a rule owned on the page beside it and goes stale silently; an example goes stale visibly, because the artifacts in it are the wrong shape. Generation is byte-deterministic — locks are walked in path order, no timestamps — because the diff is most of the value. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
<!-- Generated by `loomctl orient`. Safe to overwrite; nobody typed it.
|
|
Regenerate after adopting a document or reconciling a change. -->
|
|
|
|
# What this repository depends on
|
|
|
|
Copies of other people's documents are kept under `.loom/externals/`, at a path
|
|
that says where each came from. **They are copies: do not edit them.** Anything
|
|
you want to say about one goes in a file *beside* it, never into it.
|
|
|
|
Three moves, and each has a document that owns the rule:
|
|
|
|
- **A copy is wrong, or you needed something it does not say** — write it in
|
|
`<name>.gaps.md` beside the copy.
|
|
- **What of ours depends on a copy** — write it in `<name>.usages.md` beside it.
|
|
- **A source changed** — `loomctl external check` says so and stages the new copy;
|
|
`loomctl external apply` takes it. Neither edits anything on its own.
|
|
|
|
## `git.hypertheory-labs.dev/loom/annotating/annotating.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/annotating/raw/branch/main/.loom/published/annotating.md
|
|
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/annotating/annotating.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/bedrock/loom-directory.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/loom-directory.md
|
|
- what of ours depends on it: **nothing recorded** — no `.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/bedrock/publication.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md
|
|
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/bedrock/recording-decisions.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/recording-decisions.md
|
|
- what of ours depends on it: **nothing recorded** — no `.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/bedrock/sibling-facets.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/sibling-facets.md
|
|
- what of ours depends on it: **nothing recorded** — no `.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/bedrock/starting.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/starting.md
|
|
- what of ours depends on it: **nothing recorded** — no `.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/cart/cart.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/cart/raw/branch/main/.loom/published/cart.md
|
|
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/cart/cart.usages.md`
|
|
|
|
## `git.hypertheory-labs.dev/loom/externals/externals.md`
|
|
|
|
- source: https://git.hypertheory-labs.dev/loom/externals/raw/branch/main/.loom/published/externals.md
|
|
- what of ours depends on it: `.loom/externals/git.hypertheory-labs.dev/loom/externals/externals.usages.md`
|
|
|
|
## This repository publishes
|
|
|
|
See `.loom/published/`. What is handed over for others to depend on is
|
|
there; the rest of the repository is not hidden, it is simply not what
|
|
anybody depends on.
|