# 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.