The problem
docs/setup.md:74 and the simplycubed init next-steps output both tell the adopter:
Create the simplycubed-code GitHub App with Contents, Issues, and Pull requests permissions only
GitHub App names are globally unique, and that one is already registered:
$ gh api /apps/simplycubed-code
{"name":"simplycubed-code","owner":"simplycubed","slug":"simplycubed-code",...}
Every adopter who follows the instruction gets Name has already been taken. The step is only performable by the account that already owns the App.
Why it is not obvious
The setup flow reads as though the App is something the adopter installs from us. It isn't: the private key is what mints installation tokens, so each adopter must own their own App. That is the right design and it is what makes "runs in your GitHub, not ours" true, but the docs never say why the App has to be theirs, so the natural reading is that they should reproduce ours exactly, name included.
Sites
docs/setup.md:74
cmd/simplycubed/main.go:651 — the init next-steps line
cmd/simplycubed/main_test.go:129 — asserts that string, so it changes with the fix
Suggested shape
Tell the adopter to create an App under their own account or org with a name of their choosing, and say plainly that the private key is theirs alone and must never be shared, because a PEM authenticates as the App globally rather than per-installation.
Worth stating the two follow-on consequences in the same place, since both surprise people: their bot will be <their-app-name>[bot], not simplycubed-code[bot], and an App created under a personal account needs "Any account" visibility to be installable on an org they own.
Related: #111 and #112, the two behaviours that assume the vendor's App name.
Acceptance
Note for whoever runs this
Most of this is prose, and make check cannot judge prose. The test assertion above is the only mechanical anchor, so the diff needs a human read for tone and accuracy rather than a green gate.
Run this together with #113, which rewrites the same init output and the same docs/setup.md section. Splitting them across two runs guarantees a conflict.
The problem
docs/setup.md:74and thesimplycubed initnext-steps output both tell the adopter:GitHub App names are globally unique, and that one is already registered:
Every adopter who follows the instruction gets Name has already been taken. The step is only performable by the account that already owns the App.
Why it is not obvious
The setup flow reads as though the App is something the adopter installs from us. It isn't: the private key is what mints installation tokens, so each adopter must own their own App. That is the right design and it is what makes "runs in your GitHub, not ours" true, but the docs never say why the App has to be theirs, so the natural reading is that they should reproduce ours exactly, name included.
Sites
docs/setup.md:74cmd/simplycubed/main.go:651— the init next-steps linecmd/simplycubed/main_test.go:129— asserts that string, so it changes with the fixSuggested shape
Tell the adopter to create an App under their own account or org with a name of their choosing, and say plainly that the private key is theirs alone and must never be shared, because a PEM authenticates as the App globally rather than per-installation.
Worth stating the two follow-on consequences in the same place, since both surprise people: their bot will be
<their-app-name>[bot], notsimplycubed-code[bot], and an App created under a personal account needs "Any account" visibility to be installable on an org they own.Related: #111 and #112, the two behaviours that assume the vendor's App name.
Acceptance
simplycubed-code. Grepdocs/andcmd/for the literal.cmd/simplycubed/main.go:651names no specific App name, andcmd/simplycubed/main_test.go:129asserts the new string. That assertion is the gate's only hold on this change, so it must be updated rather than deleted.docs/setup.mdboth state, in one sentence, that the App must be the adopter's own and the private key is never shared. That is the fact whose absence causes the wrong reading.docs/setup.mdagree. They are the same instruction in two places and drift is what produced this issue.make checkgreenNote for whoever runs this
Most of this is prose, and
make checkcannot judge prose. The test assertion above is the only mechanical anchor, so the diff needs a human read for tone and accuracy rather than a green gate.Run this together with #113, which rewrites the same
initoutput and the samedocs/setup.mdsection. Splitting them across two runs guarantees a conflict.