the published surface, on a fresh root

This repository is now the public half of a split: six documents saying what to
decide, and one gap. How the cluster is built moved to jeffry/homelab-impl, which
is private because its README is an inventory of chart versions and image tags.

History starts here deliberately, and not as tidiness. The previous history
contained that inventory, and this repository is public — a deletion commit would
have removed it from the tree and left it in the log. A fresh root can only carry
what is in it.

Two pointers rewritten rather than deleted: private-access.md and .loom/README.md
both directed a reader to TAILSCALE.md and README.md at the root, which are now
private. They now say a fuller reference exists, that it is private, and how to
ask — because a public page naming a private thing as its answer is the failure
this project has now hit four times.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-07 15:19:14 -04:00
co-authored by Claude Opus 5
commit cc66e227a3
9 changed files with 566 additions and 0 deletions
+46
View File
@@ -0,0 +1,46 @@
# `.loom` — what this cluster offers
**Six documents in [`published/`](published/), written for somebody who has to
decide something.**
*What you need in order to **do** it — manifests, the rebuild guide, the tailnet
reference — is in `jeffry/homelab-impl`, **which is private**, because it sits
beside an inventory of versions and image tags. **These are what you need in order
to choose**, and none of them will send you there.*
- **[Reach something without putting it on the internet](published/private-access.md)**
— the tailnet path, and the default that will publish you by accident
- **[Put something on the internet, the way production would](published/public-access.md)**
— and what to leave out of a route so it stays portable
- **[Give something a Postgres](published/databases.md)** — operator-run, and the
volumes it will not reap
- **[Get the data back after losing the machine it was on](published/recovering-data.md)**
— two halves, and the failure that reported success for a month
- **[What a volume here can and cannot do](published/storage.md)** — node-local,
and cannot grow
- **[The git host](published/gitea.md)** — and the port that is not 22
**One thing we need and cannot find:**
[publishing a container image](gaps/publishing-container-images.md).
## If you are wondering what `.loom` is
**Nothing here requires you to know.** *They are documents in a folder; read the
one that matches your question and ignore the rest.*
**If you are curious:** the directory follows a small convention —
**[`loom/bedrock`](https://git.hypertheory-labs.dev/loom/bedrock)** — of which
two parts are used here. **`published/` is what this repository has handed over
for others to depend on**, as opposed to the rest of the repository, which is how
it is run. **`gaps/` is something we need and cannot find.**
*There is no adopted copy of that convention in this repository, and that is not
an oversight: **we made no choices about it worth recording**, and a file that
carries no delta should not exist.*
---
*Each document says only what a reader could not already know, and ends with how
to check it is still true. **None of them explains Kubernetes, Tailscale or
Postgres** — that is somebody else's documentation and copying it here would go
stale silently.*