Document GitHub agent permissions and the GitHub tool surface - #35

What changed and why

Three pages gestured at a GitHub permission that decides whether Ref may merge on your behalf ("if permitted", "depends on your GitHub permissions settings") without ever naming it or saying where it lives. This adds an Agent permissions section to the GitHub integration page that names the three toggles, their defaults, and the personal-access-token requirement for merging. It also moves the GitHub MCP tool list off the Plans MCP install page — where nobody reading about the GitHub integration would look — onto the GitHub page, and leaves a short pointer plus the endpoint URL behind on the install page.

Moved rather than mirrored so the tool list has one home and can't drift; the install page keeps the endpoint and the connection prerequisites, since that is what someone configuring a client needs there.

Verified

All in ref-tools/ref:

• Setting names, grouping, and location — plan-app/client/src/components/settings/GitHubSettingsPage.tsx: labels "GitHub Enabled", "Allow PR Reviews", "Allow PR Merges"; the latter two sit under the "PR & Issue Actions" group header. plan-app/client/src/components/settings/SettingsModal.tsx renders it as the sidebar nav item labelled "GitHub" in the Settings modal.
• Defaults — plan-app/server/src/types/agentLaunch.ts: isGitHubEnabled and isGitHubReviewEnabled are !== false (on by default), isGitHubMergeEnabled is === true (off by default). The client initialises the same three defaults.
• Merge is the single source of truth — same file: OrchestratorSettings documents that merge permission lives in github.mergeEnabled. plan-app/client/src/utils/orchestrate.tsx buildKickoffPrompt emits "Do not merge; leave merging to a human." when it is off, which is the basis for the sentence about an orchestrating agent.
• PAT requirement — GitHubSettingsPage.tsx disables the merge toggle unless a PAT is connected and links to /resources?tab=github&action=connect-pat (which resolves to the main domain, i.e. ref.tools/resources, via plan-app/client/src/lib/navigation.ts). Server side, plan-app/server/src/routes/github-mcp-handlers.ts handlePRsMerge rejects any token whose source is not personal-token.
• Tool list and conditional advertising — plan-app/server/src/routes/github-mcp.ts: GetIssue, CommentOnIssue, SearchIssues, ReadPR, SearchPRs, CreatePR always registered; ReviewPR registered only when reviews are enabled; MergePR registered only when at least one of reviews/merges is enabled, with mark_ready gated on reviews and merge gated on merges. ReadPR actions are get / get_files / get_diff / get_comments. CreatePR takes a draft flag. CreatePR was missing from the previous docs list and is now included.
• Disabling GitHub entirely — github-mcp.ts returns 403 "GitHub access is disabled in Settings." at session initialisation when enabled is false, so the tools never connect.
• Re-check at call time — github-mcp.ts re-reads settings via getGitHubSettings(userId) inside the ReviewPR and MergePR handlers, and handlePRsReview / handlePRsMarkReady / handlePRsMerge each re-assert the permission.
• Endpoint path — plan-app/server/src/index.ts mounts the router at /github-mcp; https://api.plan.ref.tools is the production plan API host.

Unverified / omitted

• Team-level control of these permissions. The settings read from per-user agent settings; I found no team-level equivalent for the GitHub toggles, so the page does not say whether an admin can set them for a team. Would be unblocked by a team-scoped settings surface or confirmation that none exists.
• Repo scoping semantics. The tool endpoint accepts a repo allowlist parameter, and an empty list allows every repo the token can reach, so "the tools only reach repos you have added" was not safe to state as written. The page says only that connected GitHub plus added repos are required.
• MergePR merge methods (merge / squash / rebase, defaulting to merge) — verified in code but left out to keep the tool table at one line per tool.
• The "auto-merge" wording in your-first-plan.mdx and the "(if permitted)" aside in multi-agent.mdx were left untouched; both are now explained by the new section, but editing them is outside this change's scope.

Conflicts

docs.json was not edited — no new pages, so no navigation change. No conflicts expected with sibling PRs beyond ordinary text merges in plans/install/index.mdx.

Generated by Claude Code