docs: the furniture an open source repo is expected to have

[nbkdoesntknowcoding]

None of this existed: no security policy, no issue templates, no PR template, and nothing telling an agent how to work here.

SECURITY.md

Draws the line that matters for this project. The interesting surface is who may reach the video and input channels — pairing bypass, token handling, injection without pairing, the helper's local IPC.

It also says plainly what is not a vulnerability, because all three get reported:

• the binaries are unsigned by choice
• the private API is the central technique, not an oversight
• the purple recording indicator appearing is correct behaviour

Issue templates

Shaped by what actually goes wrong rather than a generic form.

"It will not connect" is its own template, because it's the common failure and needs different questions. It opens by ruling out the two causes that look like faults and aren't:

• a Mac that is running but not sharing
• a second receiver already holding the connection

Both of those cost a session each today. The template also asks for the receiver's exact wording, since a named refusal and "Disconnected. Reconnecting…" are different problems with different causes.

AGENTS.md

The emerging convention, and there was a natural thing to put in it: the setup prompt that was buried in the README now lives in one place, with the README linking to it.

Alongside it, the four conventions that mislead anyone assuming the usual ones:

• the Xcode project is generated — a test file added only to the .xcodeproj silently never runs
• the protocol has golden vectors, so the wire format isn't a convenient place to add a field
• macOS permissions cannot be granted by any script — stop and ask
• mac/build/ is hundreds of megabytes and must never be committed

It also records how this codebase tests things that need two machines (extract the decision as a pure value, then break it on purpose to check the test isn't decoration), and the failure this project keeps repeating: the app knows a specific fact and displays a generic one. That has now shipped four times in different clothes, and it's worth a paragraph where the next person writing user-facing state will read it.

PR template

Asks what was not verified, and what a reviewer should be suspicious of. A change that builds and passes but was never run is a normal thing to submit — saying so is what makes it safe to review.

Also done, outside this PR

Repository topics set via the API: 16 of them, where there had been none. That was the single biggest free discovery loss on the repo.

🤖 Generated with Claude Code