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.

Rewritten to dissolve your annotations. The prompts below are answered rather than asked, and what is still open says so.

---

How the round opened

Your notes arrived as jeff-osprey.md, into a cart that had converted. Moved unedited to loom-marmalade.md, because cart allows two files and gives the test — what happens to this file when the person changes? jeff-… dies with you, so it is a person and not a stake, and loom renamed itself to loom last round saying that if you wrote here you would write into that file.

And the timing was mine, not yours. cart says do not convert while somebody is mid-thought; I asked, you approved a plan, and approving a plan is not the same as having nothing left to write.

You called that the design rather than the defect, and you are right. There is a deliberate buffer — better to make a mess occasionally, inside the cart, than to carry rules strict enough to prevent it. The shelf exists for this and did not even need to be used, because you simply wrote it again into the next round.

So it is recorded as the mechanism working, not as something to fix.

---

Settled this round

published check, and why it cannot report a verdict

reachable is gone as a word. The command is loomctl published check, so that check means one thing on both sides: ask somebody else whether what we believe is still true.

And the test is not "is this public". I built it that way and you broke it: homelab-cluster publishes six documents and is private on purpose. publication.md says what a repository has handed over for others to depend on — others, not everyone, and I read one word as the other.

So the command reports the identity it used, never a verdict:

gitea.md   200  as anonymous
gitea.md   200  as reader
gitea.md   200  as jeffry — OWNER, this proves nothing

The third line is what earns the command. publication.md says publishing is not an act you can complete alone — and a tool that verifies your publication with your own credential has helped you complete it alone, and told you it was fine.

Which makes your auth section load-bearing: a kubeconfig-shaped config is not only credentials, it is named identities you can test as. --as <context> is the whole feature.

No audience declaration

Confirmed: no field where a repository states who it published for. It would let the tool compare intent to result, and it asserts a category nobody has decided — the argument that killed init.

--as defaults to anonymous and the owner warning is always on.

Your future version is better than a declaration and does not need one: project it from the other side — read everybody's externals/ and derive who is actually depending on you. Nothing now; it is registry's shape, and registry is deliberately not built.

external list talks to git

Measured across three hosts. git archive --remote is out — gitea allows it, GitHub 422s, GitLab 404s. Partial clone is uniform:

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

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

REST would have been three dialects, not one with variations:

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

The argument for git is consistency, not thrift. One mechanism against three hosts instead of three adapters — and REST 404s on the private repository, which is the case that matters.

The failure mode to build for: --filter is a server capability and git's fallback is silent, warning filtering not recognized by server and downloading everything. --depth=1 bounds the damage, which is why both flags are there. Detect the warning and say so, rather than letting list quietly become a full clone of somebody's monorepo.

Transports, honestly

	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	not the owner's — that is the point

Two credentials per host, not one. I claimed earlier that git collapsed most of the auth story; it does not. add and check 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.

Subcommands now; plugins when somebody reports a gap

loomctl external …, loomctl published …, and loomctl beads … when it exists.

No plugin boundary yet, and your framing is better than my reasoning was: the seam gets built when it is a reported gap, not a designed one. kubectl and gh both grew plugins after somebody outside wanted in — and a gap is exactly how loom says that arrives, with a name attached and a workaround recorded beside it.

--help is the documentation surface; .loom/published/ is later

You are right about what actually happens: hand somebody an unfamiliar CLI and they run --help. That is the discovery surface, so it is the one that has to be good — for a person and for an agent, which mostly means the same thing: say what a command does and what it will not do.

A .loom/published/ for loomctl is deferred, not declined. The distinction matters, because init was declined and this is not. When somebody depends on this tool's behaviour rather than reading its help, that is when it has a contract worth publishing — and published check gets to be run against its own repository, which is a nicer acceptance test than anything I would write.

---

Measured, so nobody re-derives it

A read token, issued for one session and since deleted.

It authenticates raw HTTP on a private repository. 404 anonymous, 200 with Authorization: token or Bearer, and If-None-Match returns 304 authenticated. So add and check work on private repositories — the assumption the specimen made and nobody had run.

The gitea ETag/blob coincidence holds on private repositories too. Which changes nothing, because we do not use it.

And the specimen's sharpest claim needed correcting, by you making me try the write:

POST …/contents/…    403
  required=[write:repository]
  token scope=read:activitypub,…,read:repository,read:user

/api/v1/repos/{o}/{r} reports admin, push, pull: true for a token that cannot write — those are the account's rights. But the refusal names the scope.

A token cannot be asked what it may do. It can only be told, by being refused.

No other channel exists: /api/v1/users/{u}/tokens rejects token auth outright, and no scope header comes back on success. For us this changes the reason and not the rule — loomctl never writes, so it never provokes the one response that would tell it anything. Surface gitea's error bodies rather than replacing them, since they carry the only scope information the host emits.

---

Still open: where the credential lives

The token is deleted and we said we would decide this soon. It is the one thing this round has not answered.

What osprey fixed and still holds: it lives in ~, never in a repository, and it is named for its scope because the name is the only record.

What is new, and what makes it harder: the config is no longer only a secret. It is how you talk to a host at all — API shape, ssh on a strange port, which transport check should use, and now named identities to test as. Some of that is not secret and several people would want the same values.

The obvious answer is to split it: a host list that can be committed, and a credential file that cannot. I have not thought it through and I am naming it rather than deciding it.

Fallback if unanswered: one file in ~, kubeconfig-shaped, holding both — and an entry recording that the split is expected and was not done yet. Nothing in the repository, and nothing that reads from the repository, so that the mistake we would most regret is the one that cannot happen by accident.

---

Corrections I made this round

Kept together, because there are three and the pattern is the point.

I claimed git collapsed the auth story. It does not — I liked my answer.

I confirmed the token claim enthusiastically without testing the case that would show it wrong. You made me try the write and the refusal named the scopes.

I built published check on anonymous fetchability. Publication has an audience and the audience is not always everyone.

All three are the same shape: a result that agreed with me, and no test of the case that would not have. It is also exactly what osprey found in the ETag story — a verified fact is much louder than a rule — and I have now done it three times in a day while writing that sentence down.

Not an apology. A thing to point a test at, and the reason the log carries a belief rather than a conclusion.

---

Reviewed: what needs ssh, and what needs write

Short answer: ssh, nothing. Write access, nowhere — including here.

Every operation, and what it actually needs

	what it does	transport	credential
external list	partial clone, ls-tree the published dir	git over HTTPS	read PAT
external add	GET the raw file, record URL + ETag	HTTPS	read PAT
external check	conditional GET, If-None-Match	HTTPS	read PAT
published check	GET our own published file	HTTPS	not ours
everything it writes	files in the working tree	none	none

Measured just now: git clone --filter=blob:none --depth=1 --no-checkout over https:// on gitea — filter accepted, 124KB, ls-tree lists the published directory. I had built and measured list over ssh out of habit, and it never needed it.

The tool never writes over the network, so it needs no write credential

Including in this repository. loomctl puts files in the working tree — a fetched document, a lock, a facet — and stops. Committing and pushing are yours, under your own credentials.

That is the same reason cart gives for an agent committing and not pushing: the consequences of a push land on people it cannot experience. A tool that can push is a tool that can publish, and publishing is supposed to be an act somebody performs.

So write:repository should never appear on any token this tool is given, and a token that has it is a token we would rather not hold.

The one thing a single PAT cannot do

published check needs an identity that is not the owner's, and yours is yours. That is not an ssh problem and it is not solvable by scoping — it is the command's entire point.

Two workable identities, both HTTPS:

• anonymous — the right answer when the audience is everyone
• a second credential belonging to the actual audience — a reader account, or a token from somebody in the group you published for

And if you hold neither, the honest output is "checked as owner, proves nothing", which is still worth printing.

One thing untested, and it is the load-bearing one

Whether a gitea PAT scoped read:repository authenticates git over HTTPS, not just the API and raw files. They are different paths in gitea, and the deleted token was only ever measured against the second. Measured: an unauthenticated HTTPS clone of the private repository returns Failed to authenticate user, so something is required; nobody has confirmed that a read PAT is enough.

First thing to run against the next token. If it turns out git-over-HTTPS needs a broader scope than raw HTTP, that is an argument for keeping ssh for list after all — and it would be the only argument.

An aside that is too neat not to record

:2222 cost me three tool calls and a guess, and the tool does not need it. Every transport here is HTTPS on 443. The fact that bit me is a fact for people cloning repositories, not for loomctl — which is its own small lesson about who a published document is for.

Implementation note: keep the token out of the URL

Do not build https://<token>@host/…. git writes the remote into .git/config, and it turns up in logs and in git remote -v afterwards.

Pass it per-invocation instead:

git -c http.extraHeader="Authorization: token <t>" clone --filter=blob:none …

Nothing persisted, nothing in the repository. Which is the same rule as the credential file: the mistake we would most regret is the one that happens by accident.