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

Addendum: the third file was mine, not yours

You were writing it before I converted. Which makes this the other rule in cart, and it lands on me:

Do not convert while someone is mid-thought. Ask whether they are ready. If you convert alone anyway, say so.

I did ask, and you said the plan was good, and you were mid-thought anyway. So the check passed and was still wrong — approving a plan is not the same as having nothing left to say, and the question as cart phrases it invites the first answer when it wants the second.

Worth reporting upward: "are you ready for me to convert?" and "is there anything you are still writing?" are different questions, and only the second one would have caught this.

Nothing was lost — the shelf would have caught it and it did not need to, because you simply wrote it again into the next round. Which is the mechanism working.

---

Measured: git, and your instinct was right

Taken: published check. reachable is gone as a word.

git archive --remote is out

gitea    works (ssh)
github   HTTP 422
gitlab   HTTP 404

One round trip and no clone, and only one of three hosts allows it.

Partial clone is uniform across all three

git clone --filter=blob:none --depth=1 --no-checkout, then git ls-tree HEAD:.loom/published:

gitea     filter ok   .git=124KB
github    filter ok   .git=124KB
gitlab    filter ok   .git=144KB

Same flags, same command, same output shape. And on the repository that started all this:

jeffry/homelab-cluster   0s   124KB
  databases.md  gitea.md  private-access.md
  public-access.md  recovering-data.md  storage.md

That is the list I could not get this morning, in one command, against a private repository, in under a second.

What REST would have cost

gitea    /api/v1/repos/{o}/{r}/contents/{path}
github   /repos/{o}/{r}/contents/{path}              (api.github.com)
gitlab   /api/v4/projects/{url-encoded}/repository/tree

Three URL shapes, three JSON shapes, three auth schemes — and the private gitea repository returns 404 anonymously, so REST fails on exactly the case that matters. Your sense was right and it is now measured rather than felt.

But I overclaimed, and here is the correction

I wrote that git "collapses most of your auth section." It does not.

list discovers names over git. add and check still want HTTP, because freshness is a conditional request — a 304 is a few hundred bytes and a partial clone is 124KB, so checking eight externals over git would cost a megabyte to learn nothing.

And raw HTTP against a private repository is 404 without a token. So the honest account is:

	transport	credential
external list	git	ssh key or https creds you already have
external add, external check	HTTP	a read token, for private repos
published check	HTTP, anonymous	none, deliberately

Two credentials per host, not one. The argument for git is consistency, not thrift — one mechanism against three hosts instead of three adapters — and that argument stands on its own. The auth saving was me liking my answer.

Untested: whether a gitea read token actually works against raw HTTP on a private repository. It is the specimen's assumption and nobody has run it.

The failure mode to build for

--filter is a server capability. All three hosts here allow it; an older self-hosted gitea or gitlab may not, and git's fallback is silent — it warns filtering not recognized by server and downloads everything.

--depth=1 bounds the damage to one commit, which is why both flags are there and not just the filter. Detect the warning and say so, rather than letting list quietly become a full clone of somebody's monorepo.