chadtmiller.com/knotless
git that lives in your Atmosphere account
A README that starts from where a repository lives
MergedThis rewrites the README from the reader's side: what knotless is, the four commands to try it, the parts of a forge and who runs each, agents, a table of what has to run, how a PDS holds a repository, performance and status. It reads well top to bottom. The docs check passes, so links, anchors and the diagram are fine. The other checks that ran also pass, and test was still running when I looked.
I spot-checked a few claims against the repo and they hold. Compaction starts on the owner's git push once a repository holds 32 packs, as docs/design/storage.md says, and the AGENTS.md pointers are accurate. I did not check the platform list for the installer, the "about 130 MCP tools" count, or the benchmark figures against docs/reference/performance.md. They are easy to let drift, so a quick re-read before merging would help.
This is docs only and touches no client source, so no change file is needed. No changes asked.
8 passed, 3 skipped
The README is written again from the reader's side: where a repository lives on a forge, what changes when it lives in an atproto account, the four commands to try it, and only then how it works. It also stops saying things the code no longer does. Docs only; worth reading top to bottom once, as it is the front page.
Claude Fable 5.2
What changes
The order. It opens on what knotless is and why an account is a better home for a repository than a forge's servers, places the name against Tangled's knots in two sentences, and goes straight to install, log in, push and clone. "The rest of a forge" then gives each piece as the answer to a question: how collaborators push (the gateway), who gathers pulls and issues (the appview), who runs CI (runners), what is private. Agents have a section of their own, with a commit made without a checkout, a pull and the MCP server.
What has to run. The list of components is a table of each piece, what it adds and who runs it, under a diagram of who writes where.
knotless-agent, which the old list left out, is in it.How a PDS holds a repository. The table of four record types is gone: the page keeps the claim's compare-and-swap, which is what makes a reader believe a PDS with no locks can take concurrent pushes, and links Storage for the rest.
Performance. The table is the one
docs/reference/performance.mdnow has, over https with connecting counted, with the requests each operation makes, and says what a push costs a client with an appview.Status names no version, so a release does not have to touch it.
Why
The old page opened with a tagline and a feature list, and had drifted from the code:
git push.docs/design/security.mdlists three.How it was checked
Written as the
docsskill lays out: two agents read the code and wrote a fact inventory against the old page, a third wrote the page from the facts without seeing the old one, and each claim was then checked against the inventory, and the doubtful ones against the code. The numbers are from the bench run described in The bench reaches the PDS over https, and counts connecting.node harness/docs.mjspasses here: every link and anchor lands and the diagram draws.git clone https://knotless.dev/chadtmiller.com/knotlesswas tried with plain git (ls-remote).Shortcomings
docs/README.md, which this links as the index, does not list three design pages that exist (packages.md,pages.md,reusable-workflows.md). Not changed here.