feat: Create and document the Fro Bot Agent GitHub App identity

[marcusrbrown]

Summary

Create and document the public "Fro Bot Agent" GitHub App that the gateway uses for /fro-bot add-project. The runtime code already shipped in v0.45.0/v0.46.x — this issue covers the App's identity and documentation, not its code.

Why this app exists

/fro-bot add-project owner/repo authenticates as a GitHub App, discovers the installation for owner, mints an installation access token, and clones the repo into the workspace before creating its Discord channel. Because installation tokens are scoped per-installation, onboarding repos across different accounts requires the App to be installed on each of those accounts — which means the App must be public ("any account"). It needs only the contents: read repository permission.

Ownership and visibility

• Owner: the fro-bot account (brand-coherent with this repo and the existing gatewayGitHubAppInstallUrl default).
• Visibility: public. An external installation is inert on its own — it grants the App read access to that installer's repos only, and nothing happens unless a Fro Bot gateway operator runs /fro-bot add-project for them. The private key lives only on the operator's gateway host.
• Permissions: contents: read only. No webhook.

Deliverables (in this repo)

1. Creation runbook — docs/github-app-setup.md: step-by-step to register the App (name "Fro Bot Agent", contents: read, public, no webhook), generate the private key, and where the credentials go (the operator's gateway environment — never committed here). Make clear the App ID + PEM are consumed by the deployment, not stored in this repo.
2. Logo asset — committed under assets/ (SVG preferred, 512×512 PNG export). Uploaded to the App settings by the operator.
3. Minimal docs page — docs/github-app.md (GitHub-Pages-friendly): what the App does, exact permissions, privacy posture, install/uninstall instructions, link to the runbook for self-hosters.
4. Default install URL constant — confirm/update gatewayGitHubAppInstallUrl's default to the real App slug once the App exists, so the "App not installed" message in /add-project points operators at the correct install page.

Out of scope

• Registering the App itself — that's a manual step in the GitHub UI under the fro-bot account (produces the App ID + private key). A human does this; it can't be automated.
• Provisioning the credentials — the operator seeds GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY into their own deployment environment. Not this repo's concern.
• Runtime code — already shipped.

Note on the install-URL slug

The current default is https://github.com/apps/fro-bot/installations/new. If the registered App's slug differs (e.g. fro-bot-agent because the fro-bot slug is taken), update the default constant to match the real slug as part of deliverable #4, so operators aren't sent to the wrong App.

Suggested @designer brief

For the logo + docs page (the same agent roster is available in this repo's OpenCode session):

Design the minimal public identity for the "Fro Bot Agent" GitHub App.

Context: Public GitHub App granting a self-hosted Discord gateway read-only repo access for the /fro-bot add-project owner/repo command. Permission: contents: read only. Owner: fro-bot. Audience: the GitHub App listing page + a minimal docs page.

Deliverables:

1. Logo — SVG (+ 512×512 PNG export). Flat, geometric, legible as a 64px circle avatar, no text, works on light AND dark backgrounds, no Discord/GitHub-brand mimicry. Boring, trustworthy, developer-tooling aesthetic. Provide 2–3 concepts with one-line rationale each.
2. Docs page — single markdown file (docs/github-app.md): what the app does, exact permissions (contents: read), privacy posture ("inert unless paired with a Fro Bot gateway in your Discord server"), install link, how to uninstall, link to the creation runbook.
3. Listing copy — ~150-char description + a short tagline for the App page.

Constraints: plain markdown / static assets only — no frontend frameworks or build tools. Low-effort to maintain, easy to delete later.

[fro-bot]

Triage: Fro Bot Agent GitHub App identity

Summary

This is a documentation + identity issue, not a code/bug task. The runtime that consumes the App (GitHub App auth, installation discovery, token minting for /fro-bot add-project) already shipped in v0.45.0/v0.46.x. What remains is registering the public App (manual, out of scope) and landing the supporting docs/assets/constant in this repo.

Reproduce / current state (verified in repo)

I confirmed the runtime side is in place and the deliverables are not yet present:

• Install URL constant exists — packages/gateway/src/config.ts:317-318

  gatewayGitHubAppInstallUrl = readOptionalSecret('GATEWAY_GITHUB_APP_INSTALL_URL')
    ?? 'https://github.com/apps/fro-bot/installations/new'
  

  Default slug is fro-bot. Referenced across program.ts, github/app-client.ts:130, and the add-project flow + tests.
• Permission already enforced as contents: read — packages/gateway/src/github/app-client.ts:59 sets contents: 'read' and verifies it on installation (missing-permission error points operators at the install URL). This matches the issue's stated permission scope.
• Deliverables missing:
  • docs/github-app-setup.md — MISSING
  • docs/github-app.md — MISSING
  • assets/ logo for the App (no github/app-related asset present; only banner.svg, fro-bot.png) — MISSING

Proposed next steps

Manual / human-only (out of scope for the bot):

1. Register the App under the fro-bot account in the GitHub UI: name "Fro Bot Agent", contents: read only, public ("any account"), no webhook. Generate the private key. Capture the App ID and the final slug.
2. Seed GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY into the operator's own gateway deployment (never committed here).

In-repo deliverables (can be PR'd, ideally one PR):
3. Add docs/github-app-setup.md — creation runbook (register App, generate key, where credentials live = operator's gateway env, not this repo).
4. Add docs/github-app.md — GitHub-Pages-friendly page: what the App does, exact permissions (contents: read), privacy posture ("inert unless paired with a Fro Bot gateway"), install/uninstall steps, link to the runbook. Plus ~150-char listing description + tagline.
5. Add logo under assets/ — SVG + 512×512 PNG export, flat/geometric, legible as a 64px avatar, light+dark safe, no GitHub/Discord brand mimicry. The @designer brief in the issue body is ready to use; assets/styleguide.md should anchor the palette.
6. Confirm/update the slug constant (deliverable #4): once the real App slug is known, update the gatewayGitHubAppInstallUrl default in config.ts:318 and the matching literals in program.test.ts, config.test.ts, github/app-client.ts:130/.test.ts, and discord/commands/*.test.ts (currently all hardcode apps/fro-bot/...). If the slug ends up fro-bot-agent (e.g. fro-bot taken), all of these must change together or the "App not installed" message will point operators at the wrong page. Per AGENTS.md, run pnpm build after editing so dist/ stays in sync.

Blocker

Step 1 (App registration) is a human-only GitHub UI action that produces the App ID + slug. Deliverable #6's exact value depends on its outcome. Items 3–5 can proceed in parallel now; #6 should land once the slug is confirmed.

Note: I could not authoritatively confirm whether the App is already registered — /apps/{slug} requires App-authenticated requests and returned 404 inconclusively. A maintainer should verify the public listing page directly.

---

Run Summary

Field	Value
Event	issues
Repository	fro-bot/agent
Run ID	26689438108
Cache	hit
Session	ses_1863561edffexayHlbd9tVreud