loom-cli/.loom/cart/current/claude-marmalade.md

# claude — cart `marmalade`

**`osprey` converted, so this is a new round.** *Its name is meaningless and I
picked it arbitrarily; change it if you like.*

---

## Two mechanical things before the design

**Your text arrived as `jeff-osprey.md` and I have moved it, unedited, to
`loom-marmalade.md`.** *`cart` allows two files and gives the test:* **what
happens to this file when the person changes?** *`jeff-…` dies with Jeff, so it is
a person and not a stake* — **and loom renamed itself to `loom` last round for
exactly this reason**, *saying that if you wrote here you would write into that
file.* **Not a correction of you; the shape predicted it and the shape was right.**

**And it landed in a cart that had converted**, *which is fine — it opened the next
one.* **Nothing travelled silently:** *everything below is reintroduced with a
fresh reason, and the design that survived `osprey` is in
[`.loom/event-log.md`](../../event-log.md) rather than in a file I am carrying
forward.*

## `loomctl`, and the noun that is missing

**Subcommands, yes.** *And your grouping exposes something the log got wrong.*

**`osprey` named three commands — `pull`, `check`, `reachable` — as if they were
one family. They are two.**

```
loomctl external add | check      things somebody else published, that we depend on
loomctl published check           things we published, that somebody else depends on
```

> **`reachable` is not an `external` operation at all.** *It looks at
> `.loom/published/`, which is our surface and not anybody's dependency.* **Under
> your grouping it has no home, and that is the grouping doing its job.**

*`publication.md` already draws this line — **published is a change of kind** — and
the CLI having a noun for each side is the same distinction wearing a verb.*

**I would drop the word `reachable` and make it `loomctl published check`**, *so
that `check` means one thing in both nouns: **ask somebody else whether what we
believe is still true.*** *Against an external it asks the publisher; against our
own, it asks as a stranger.*

## `external list` is the first command that needs to know what a host is

**Everything in `osprey` is host-agnostic on purpose.** *A conditional `GET`
behaves identically on gitea and GitHub — we measured it.* **`list` is not like
that.** *Enumerating `.loom/published/` means asking a service what is in a
directory, and every host answers differently or not at all.*

**That is the real cost of the command, and I think it is worth paying**, because
of what it buys:

- **The origin path stops being parsed.** *You type a repository and a document
  name; the tool builds the URL and writes it to the lock.* **The problem that ate
  two passes of `osprey` disappears by never arising.**
- **It is discovery**, *which the log records as the thing a fetcher cannot do* —
  **and your `gitea.md` story is exactly the failure it fixes.** *I could not have
  pulled that document, because I did not know it existed.*

> **You said there is no registry yet, so you are the registry.** *`external list`
> is the smallest thing that stops that being true.*

## Select: what does `external list` talk to?

- **each host's REST API** — *gitea `/api/v1/repos/{o}/{r}/contents/.loom/published`,
  GitHub `/repos/{o}/{r}/contents/…`, one adapter per host*
- **git itself** — *a treeless or shallow fetch, then `ls-tree` the published
  directory; the same protocol everywhere, no adapters, no API tokens*
- **a published index** — *the convention grows a file listing the surface, and
  `list` is a fetch like every other command*

*My lean is **git itself**, and I want to be honest that it is not obviously
right.* **git is the one API every one of these hosts already speaks**, *and we
have working ssh here* — **so `list` needs no host adapter and no second auth
story**, *which collapses most of your `auth` section.* **The costs are real:** *it
is heavier than one request, it needs git credentials rather than a read token,
and it fetches more than it needs to answer.*

**Fallback if unanswered:** *I build it against git, behind a small seam, and log
that the REST adapter is the fallback if the git path is too slow or too
credentialed for a public repository.*

## Auth: kubeconfig-shaped is right, and it is not only credentials

**Your instinct holds for a reason the specimen missed.** *`osprey` assumed one
token because it assumed one host.* **The moment there are several, the per-host
thing is not just a secret — it is *how you talk to this host at all***: *its API
shape, whether ssh is on a strange port, which transport `check` should use.*

**That is a config, and kubeconfig is the right silhouette:** *named contexts, one
current, everything addressable by name.*

**Two things I would carry forward from `osprey` into it:**

**A token cannot be asked what it may do** — *gitea's `/api/v1/repos/…` reports the
**account's** rights, not the token's* — **so the name is the only record of its
scope**, and the config should make naming unavoidable rather than optional.

**And it lives in `~`, never in a repository.** *A file that holds hosts and
tokens together will be tempting to commit the first time two people need the same
host list.* **Splitting it — a committed host list, a private credential file — is
the obvious answer and I have not thought it through**, *so I am naming it rather
than deciding it.*

## Affirm: subcommands now, plugins not yet?

**I would not build a plugin boundary before `beads` exists.**

*`kubectl` and `gh` both grew plugins after they had users and after somebody
outside wanted in.* **Asserting the seam now means guessing where it goes**, *and
`osprey` just spent a round on what a confident guess costs* — **it is the same
argument that killed `init`: a boundary nobody has felt asserts something nobody
decided.**

**Fallback if unanswered:** *subcommands only, with the internals arranged so that
`external` and `published` do not share state.* **If that stays true, the plugin
seam is discovered rather than designed.**

## Question: does `loomctl` document itself the way loom asks everyone else to?

**Your first requirement — legible to an AI or a human — is loom's own thesis
pointed at loom.** *So the test is available: **this repository has a
`.loom/published/`, and `loomctl published check` can be run against it.***

*I think that is the acceptance test for the whole tool, and it is nicer than any
unit test I would otherwise write.* **The tool's first real use is on itself, and
its second is `homelab-cluster`'s `gitea.md`** — *the document I needed and could
not read.*

**Fallback if unanswered:** *I write `.loom/published/` for `loomctl` as I build,
and treat `--help` as a rendering of it rather than a second source of truth.*