johnandersen777.bsky.social/knotless
git that lives in your Atmosphere account
Forked from chadtmiller.com/knotless
0
0
# Context to give a writer
Copy what the page needs into its context file. Give only the glossary
terms its facts use: a writer given more atproto than that teaches the
protocol instead of the page.
## knotless in three lines
- A git repository is a few kinds of record in its owner's atproto account:
one record per ref (with a generation counter), and git packs. Pushing
writes records to the owner's PDS. Nothing else is the source of truth.
- Pulls, issues, comments and pull states are records in each author's own
account. An optional server, knotless-serve, indexes them (the
"appview"), caches git data, and draws the web pages.
- Collaborators can't write to the owner's account, so they push through a
"gateway" the owner delegates to. A repository record lists its
`collaborators`, and its `runners`: the accounts whose checks readers show.
## The reader
Someone who knows git and CI well, and knows roughly what atproto is:
accounts keep records on a server called a PDS. They do not know
atproto's details. Explain an atproto term the first time it matters, in
a clause, and link to https://atproto.com for more.
## Glossary
- **PDS**: the server that holds an account's records and blobs, and signs
its repo. The owner's PDS is the authority on where a ref points.
- **DID**: an account's permanent ID (`did:plc:…`). A **handle**
(`alice.example.com`) is a changeable name that resolves to it.
- **record / record key (rkey)**: a JSON document in a collection (an NSID
such as `dev.knotless.ref`) in an account, addressed by a key. Keys sort
as strings, so a shared prefix can be listed with one `listRecords` scan.
- **TID**: a time-ordered record key.
- **AT-URI**: `at://<did>/<collection>/<rkey>`, the address of one record.
- **blob**: binary data stored beside records (large packs, logs, images).
- **`applyWrites`**: one call that writes several records together, or none.
- **Jetstream / firehose**: public streams of every account's record
changes. Jetstream is a JSON relay whose frames are unsigned.
- **appview**: a service that indexes records across accounts.
- **service token**: a short-lived signed token one account's PDS issues
for calling another service as that account.
- **OAuth session**: a grant an account gives a client to write as it,
within a scope.
- **space**: the permissioned-data alpha's private record store, which
only its members read.
- **lexicon**: the schema for a record type (`lexicons/dev/knotless/`).
- **label**: a moderation tag a labeler publishes about a record or account.
## Pages to link
Design: `README.md` (overview), `storage.md`, `gateway.md`, `access.md`,
`identity.md`, `collaboration.md`, `merge-queue.md`, `runner.md`,
`serve.md`, `security.md`, `prior-art.md`. Reference: `../reference/cli.md`,
`api.md`, `mcp.md`, `workflows.md`, `performance.md`,
`runner-internals.md`. Guides under `../guide/`. Link to them rather than
restating them.