Parent: #1936
Problem
A few first-run operator experience gaps surfaced during a portability review, distinct from the broader image-first onboarding work already tracked in #1938:
- The environment variable that grants control-panel "operator" access is not documented anywhere and defaults to nobody having access — a first-time operator who signs into their own instance's dashboard gets silently zero privileges with no explanation.
- A working one-click GitHub App setup flow exists in the codebase but isn't mentioned in the self-hosting docs at all; the docs instead describe manual GitHub App creation, and the manually-documented recommended permission set does not match what the one-click flow actually requests — an operator who reads the docs and creates their App manually with the documented (narrower) permissions could unexpectedly break auto-merge without any indication why.
- A handful of other environment variables the app genuinely reads at runtime (a webhook body-size guard, the visual-review browser endpoint, MCP read/write allowlists, AI spend-budget controls) are absent from the example env file, forcing an operator to grep source to discover them.
Requirements
- Document the admin-access environment variable clearly in both
.env.example and the relevant self-hosting doc page, including what happens when it's unset (fail-closed, no operator access) so it isn't mistaken for a bug.
- Either document the one-click GitHub App setup flow as the recommended path, or reconcile the documented manual-permission set with what the flow actually requests — pick one source of truth and make the docs match the code.
- Add the identified missing environment variables to
.env.example with a short description each.
Deliverables
.env.example and doc updates for the admin-access variable.
- Doc + code reconciliation for the GitHub App permission set (either documented one-click flow, or corrected manual instructions).
.env.example entries for the other identified missing variables.
Acceptance criteria
- A first-time operator can find, in one documented place, how to grant themselves control-panel access.
- The documented GitHub App permissions match what the app actually needs for its default-enabled features.
- No currently-functional environment variable is undiscoverable without reading source.
Expected outcome
A new operator can complete first-time setup end to end using only the published documentation, without needing to read application source to find working configuration.
Parent: #1936
Problem
A few first-run operator experience gaps surfaced during a portability review, distinct from the broader image-first onboarding work already tracked in #1938:
Requirements
.env.exampleand the relevant self-hosting doc page, including what happens when it's unset (fail-closed, no operator access) so it isn't mistaken for a bug..env.examplewith a short description each.Deliverables
.env.exampleand doc updates for the admin-access variable..env.exampleentries for the other identified missing variables.Acceptance criteria
Expected outcome
A new operator can complete first-time setup end to end using only the published documentation, without needing to read application source to find working configuration.