quince: reconcile through the tool, write the facets, and adopt gitea.md

The whole loop ran on a real change with a cart open for the first time: check staged externals.md as a polad, apply moved it and its lock, and the new confidentiality rule arrived through the tool rather than through somebody saying so. Answers loom's completeness case. A 200 says the document moved and nothing about whether the casting still covers it — but the mechanism exists and we had not built the thing it needs. check prints the document's .usages.md when it stages a polad, and for an agreement that is the file the roles are cast in. It failed here because externals.md had no facet at all. So both are written: externals.usages.md naming which Go file implements which rule, and a v1 section on cart.usages.md recording the casting, that we got it wrong before it was written down, and that osprey and marmalade stay in history unrewritten. Implements the adopted confidentiality rule as far as it can be implemented. add warns when a fetch needed a credential, and says plainly that it cannot see who may read the repository the copy lands in. Reference-only adoption is recorded as not yet implemented rather than as a gap, because the gap is ours. Adopts gitea.md, now that homelab-cluster is public — the document that cost three tool calls and a guess this morning, with a facet recording that its :2222 fact is a fact for people and not for the tool, whose every transport is HTTPS on 443. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris
2026-09-07 15:26:27 -04:00
parent c0ae0e892f
commit 6a5966ba99
8 changed files with 237 additions and 1 deletions
@@ -0,0 +1,69 @@
+# The git host
+
+**`git.hypertheory-labs.dev`**, on the public internet, with a real certificate.
+**This is where the `loom/*` repositories live.**
+
+---
+
+## SSH is on 2222, and it is not optional to know
+
+**Git-over-SSH does not pass through Traefik** — it is raw TCP, on a
+`LoadBalancer` that binds a host port on every node. **Port 22 is held by each
+node's own `sshd`**, so the service is on **2222**.
+
+```
+ssh://git@git.hypertheory-labs.dev:2222/<org>/<repo>.git
+```
+
+**A clone URL without the port will not work**, and the failure looks like an
+authentication problem rather than a wrong port.
+
+```sh
+ssh -T -p 2222 git@git.hypertheory-labs.dev     # "Hi there, <name>!" once a key is registered
+```
+
+*`Permission denied (publickey)` from a node IP is the **success** case for an
+unregistered key — the server answered and offered its host key.*
+
+## Registration is closed
+
+**One account.** *The anonymous landing page serves no sign-up link.* **If you
+need access, somebody creates it for you.**
+
+## Two things that will surprise you
+
+**Sessions do not survive a restart.** *There is no Redis or valkey here — cache
+and session are in memory, deliberately.* **The queue is on disk and does
+survive.** *With one user this is nearly free; it stops being free if this ever
+grows real users.*
+
+**If the control-plane node is down, this is down.** *The repository volume is
+pinned to it and cannot move.* **Postgres is unaffected** — it replicates — *but
+the git objects live on a volume that cannot be rescheduled.* See
+[storage](storage.md).
+
+## Never pin the chart below what is deployed
+
+**Gitea does not migrate its schema backward.** *An older chart fails in the
+`configure-gitea` init container with "database is for a newer Gitea", the
+rollout hangs, and the old pod keeps serving.*
+
+**Check `helm history` before setting a version.** *This has already happened
+once.*
+
+## The container registry
+
+**Gitea has one. Access to it is not worked out**, and that is an open problem
+rather than an omission — see [`gaps/`](../gaps/publishing-container-images.md).
+
+---
+
+## Checking this is still true
+
+**Verified 2026-09-03**, after a rebuild from scratch.
+
+```sh
+kubectl get svc gitea-ssh -n gitea         # EXTERNAL-IP = node IPs, 2222/TCP
+kubectl get ingress -n gitea               # CLASS=traefik, git.hypertheory-labs.dev
+curl -sS -o /dev/null -w "%{http_code}\n" https://git.hypertheory-labs.dev/
+```
@@ -0,0 +1,25 @@
+# Usages — `gitea.md`
+
+**Adopted 2026-09-07, and it is the reason this tool exists.**
+
+*This page was published, accurate, and unreachable when it would have helped.
+The `:2222` fact cost three tool calls and a guess, and the page says:* **"A clone
+URL without the port will not work, and the failure looks like an authentication
+problem rather than a wrong port."** *It named the failure before it happened.*
+
+## What we use
+
+**SSH is on `2222`, and a clone URL without the port fails as an auth error.**
+*Used by anybody working in this repository by hand.* **Not used by `loomctl`** —
+*every transport it has is HTTPS on 443* — **which is worth saying, because it is
+the difference between a fact for people and a fact for the tool.**
+
+**Registration is closed; one account.** *Which is why
+`internal/external/polad.go` and `internal/external/external.go` are built around
+a single reader identity per host, and why nothing here tries to check a
+publication as somebody else.*
+
+## What we expected and did not find
+
+**Nothing.** *The gap this document would have filled was ours, not its: it was
+private, and now it is not.*