docs(github-app): public docs, setup runbook, and app logo

[marcusrbrown]

Adds the in-repo identity deliverables for the Fro Bot Agent GitHub App (issue #703).

Deliverables

• docs/github-app.md — public-facing page: what the app does, the exact contents: read permission, privacy posture (inert unless paired with a self-hosted gateway; no webhook, no data collected here), install/uninstall steps, and the listing description + tagline.
• docs/github-app-setup.md — operator runbook: app registration, fro-bot ownership, and where credentials live (the operator's own gateway env, never committed), linking to the deploy README for secret wiring.
• App logo — a flat geometric mark derived from the Fro Bot head, legible as a 64px circle avatar and safe on light and dark: assets/github-app-logo.svg (primary), assets/github-app-logo-alt.svg (variant), and a 512×512 PNG export for upload.

Docs reference the published slug fro-bot-agent and the /fro-bot add-project command. Static markdown and assets only — no build tooling.

[fro-bot]

Verdict: PASS

Docs-and-assets-only PR (2 markdown files, 2 SVGs, 1 PNG; no build tooling, no code paths touched). I verified every factual claim in the docs against the codebase and they are accurate.

Verification performed:

• contents: read permission claim — matches the enforced minimum in packages/gateway/src/github/app-client.ts:59 (contents: 'read'), and the docs correctly state nothing else is requested.
• Env var names GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GATEWAY_GITHUB_APP_INSTALL_URL — all present in packages/gateway/src/config.ts:328-331.
• *_FILE convention (GITHUB_APP_ID_FILE, GITHUB_APP_PRIVATE_KEY_FILE) — matches deploy/compose.yaml:31-32.
• Secret file paths deploy/secrets/github-app-id / github-app-private-key — match deploy/README.md:185-186.
• Slug fro-bot-agent and install URL — match the default in config.ts:331 and app-client.ts:130.
• /fro-bot add-project command — matches packages/gateway/src/discord/commands/add-project.ts.
• assets/github-app-logo-512.png is a valid 512×512 RGBA PNG; both SVGs are well-formed.
• Relative doc links (./github-app-setup.md, ../deploy/README.md) resolve correctly.

Blocking issues

None.

Non-blocking concerns

• Command name drift between docs. These new docs correctly use /fro-bot add-project (matching the code). However the existing deploy/README.md:192 still refers to it as the /add-project command. Not introduced by this PR, but since this PR establishes /fro-bot add-project as canonical, a follow-up to align deploy/README.md would prevent operator confusion.
• Public link vs. install link. github-app.md points users to https://github.com/apps/fro-bot-agent (public page) while the gateway default is .../installations/new. This is intentional and correct for the two different audiences (human reader vs. programmatic install prompt) — flagging only so it isn't mistaken for an inconsistency.

Missing tests

None required. This PR adds only static markdown and image assets with no executable behavior, so there is nothing to unit-test. The underlying config/permission invariants the docs describe are already covered by packages/gateway/src/config.test.ts (env var loading, install URL default/override) and the permission check in app-client.ts.

Risk assessment (LOW): No code, config, or runtime behavior changes. Blast radius is limited to documentation and avatar assets. Zero regression and zero security exposure — the docs accurately describe the existing least-privilege (contents: read, no webhook) posture rather than altering it.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	26708723003
Cache	hit
Session	ses_182a9dbf1ffe1iqS5vY2j5Mpc9

[fro-bot]

Verdict: PASS

Re-reviewed after commit db6f2d6 (which restructured the trailing copy section of docs/github-app.md from "Listing copy" into a labeled "GitHub App settings copy" block). Still docs-and-assets-only — no code paths touched. All factual claims remain accurate against the codebase.

Verification (re-confirmed for the new content):

• contents: read claim — matches the enforced minimum in packages/gateway/src/github/app-client.ts:59.
• /fro-bot add-project <repo-url> — matches packages/gateway/src/discord/commands/add-project.ts.
• Slug fro-bot-agent / install URL — match config.ts:331 and app-client.ts:130.
• Homepage URL https://github.com/fro-bot/agent — correct repo.
• Badge background 0D0216 — consistent with the Void color used in the logo SVGs (fill="#0D0216").
• Env vars, *_FILE convention, and secret paths in github-app-setup.md — unchanged and still match config.ts, deploy/compose.yaml:31-32, and deploy/README.md:185-186.
• Both SVGs well-formed; github-app-logo-512.png is a valid 512×512 RGBA PNG.

The new "Description" block is correctly labeled as copy-to-paste content and its claims (contents: read, no webhook, no data collected, inert) are consistent with the rest of the doc and the implementation.

Blocking issues

None.

Non-blocking concerns

• Command name drift between docs. These docs use the canonical /fro-bot add-project (matching the code), but deploy/README.md:192 still calls it /add-project. Pre-existing, not introduced here; a follow-up to align deploy/README.md would avoid operator confusion.
• Public link vs. install link. github-app.md links the public page https://github.com/apps/fro-bot-agent while the gateway default is .../installations/new. Intentional (human vs. programmatic audience) — noted only to pre-empt a false-positive inconsistency flag.

Missing tests

None required. Static markdown and image assets with no executable behavior. The config/permission invariants the docs describe are already covered by packages/gateway/src/config.test.ts and the permission check in app-client.ts.

Risk assessment (LOW): No code, config, or runtime behavior change. Blast radius limited to documentation and avatar assets. Zero regression and zero security exposure — the docs describe the existing least-privilege (contents: read, no webhook) posture rather than altering it.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	26708866947
Cache	hit
Session	ses_182a9dbf1ffe1iqS5vY2j5Mpc9