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.