The questions each design page answers

In roughly the order a reader asks them. Start a page's context from its list, and add what the facts raise. A page with no list here gets one written the same way: what the thing is, what problems shape it, then one question per mechanism.

storage.md

1. What is a knotless repository, physically, in an atproto account?
2. What limits of a stock PDS shape the design, and what does each force?
3. How are records keyed, and why does that make one repository one prefix scan?
4. How does a push work, round trip by round trip, and how is it safe against a concurrent push to the same ref without locking the account?
5. How are large packs stored?
6. How does a fetch find what it needs, and how does it survive a compaction mid-walk?
7. Why and how are packs compacted, and what do old claims and grace periods protect?
8. How do commits without a checkout work, and how do they handle a moved branch?
9. What does a client cache locally, and how do processes share it safely?
10. What does the git remote helper refuse, and why: fetch first, forced pushes, a handle that changes owner?

serve.md

1. What is knotless-serve, and why is it optional? What is the source of truth if not it?
2. What problems shape it? Reads must be fast though PDSes are far away. Pulls and issues live in many accounts and need an index. Collaborators can't write to the owner's account. Moderation needs a place to happen. It must be cheap to run, and safe to run by anyone.
3. How does the cache stay fresh: TTL, feeds, Jetstream vs firehose, and the trust each one implies?
4. How are git and the object API served from it?
5. What does the appview index, how is it filled and rebuilt, and what does it answer?
6. How do takedowns, reports and labels work here?
7. What does the gateway role add? Keep this to a summary and link to gateway.md.
8. How do the web pages get their data (XRPC queries, the SvelteKit app), and what do they do to stay fast and safe: highlighting, diffs, Markdown and Mermaid, raw files, caching?
9. How are social cards drawn and cached?
10. What do /_status and /mcp do?
11. With --private, what changes, and why does it refuse to listen beyond loopback?

collaboration.md

1. Where do pulls, issues, comments and reviews live, and why there?
2. How do records refer to a repository so they survive renames? Summary only; link to identity.md.
3. What is an item's state, who may change it, and how is the current one decided?
4. How does a client list everything said about a repository, public and private, and see an item opened a moment ago?
5. How does merging work, step by step, into normal and linear branches, directly and through the gateway?
6. What does a merge record, and how do closing keywords close issues?
7. How are pulls compared and diffed?
8. How do branch renames and retargeting keep pulls attached?
9. How do forks work, including private ones?
10. How does moderation work: the owner's hides and blocks, reports, takedowns and labels, and who applies which?
11. How do the merge gate and merge queue touch merging? One paragraph each, linking to runner.md and merge-queue.md.

merge-queue.md

1. What problem does the merge queue solve, compared with merging pulls one at a time?
2. How does a pull join, leave, or get ejected, and who may do each? Where is that recorded?
3. How does a runner build a batch, check it, and land it?
4. What happens when a batch fails (halving), and when a pull conflicts?
5. How does the next batch run ahead, and what happens when the one under it fails or changes?
6. How quickly is a newly queued pull noticed, and from where?
7. What happens when the branch, a pull's head, or the queue moves while a batch is being checked?
8. How does the queue interact with other runs: priority, pulls not in the queue, reuse of passes?
9. What does landing write: the merged state, closed issues, deleted branches?

runner.md

1. What is knotless-run, and what does it produce?
2. What problems shape its design? Events that can't be trusted. Pull code from strangers. Deploys that must not be cut off. Many pulls retesting on every merge. Caches that must not leak between trust levels. A runner that stops and starts.
3. How does it find out something changed, and why does it never run what an event claims?
4. What exactly does it run for a push, and for a pull? Which commit, which workflows?
5. Whose code runs automatically, and whose waits for the owner?
6. In what order do runs get a job, and why that order?
7. What happens to a run when a newer commit arrives, and what is different for deploys (superseded: finish)?
8. What happens when the runner stops or crashes, and when it starts again?
9. Where and how does a step run: executors, checkout, environment, time limits?
10. How do caches stay fast without leaking between trust levels?
11. How do secrets reach a step, and how are they kept out of logs and away from branches?
12. What does a check record hold, how is it keyed, and why are only some accounts' checks shown?
13. How do reruns and run-by-name work?
14. How does knotless pull merge use checks (the merge gate)?
15. How does the merge queue use the runner? Keep this to a short summary and a link to merge-queue.md.