diff --git a/assets/github-app-logo-512.png b/assets/github-app-logo-512.png
new file mode 100644
index 00000000..e54577ed
Binary files /dev/null and b/assets/github-app-logo-512.png differ
diff --git a/assets/github-app-logo-alt.svg b/assets/github-app-logo-alt.svg
new file mode 100644
index 00000000..89391f19
--- /dev/null
+++ b/assets/github-app-logo-alt.svg
@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="100%" height="100%">
+  <defs>
+    <!-- Dark Radial Gradient for deep space feel -->
+    <radialGradient id="darkBg" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#1A0B2E" />
+      <stop offset="100%" stop-color="#0D0216" />
+    </radialGradient>
+    
+    <filter id="cyanGlow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="3" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Circular Mask/Token Base with glowing Cyber Cyan ring -->
+  <circle cx="128" cy="128" r="124" fill="url(#darkBg)" stroke="#00BCD4" stroke-width="4" filter="url(#cyanGlow)" />
+
+  <!-- Afro Base & Texture Bumps (Purple Mid for contrast on dark bg) -->
+  <circle cx="128" cy="108" r="88" fill="#2D1B4E" />
+  <circle cx="64" cy="140" r="32" fill="#2D1B4E" />
+  <circle cx="192" cy="140" r="32" fill="#2D1B4E" />
+
+  <!-- Faceplate (White with stroke matching the Afro) -->
+  <rect x="80" y="96" width="96" height="116" rx="48" fill="#FFFFFF" stroke="#2D1B4E" stroke-width="8" />
+
+  <!-- Visor Slot (Void) -->
+  <rect x="92" y="124" width="72" height="32" rx="16" fill="#0D0216" />
+
+  <!-- Optic Main (Cyber Cyan) -->
+  <rect x="102" y="132" width="32" height="16" rx="8" fill="#00BCD4" filter="url(#cyanGlow)" />
+  
+  <!-- Optic Secondary (Solar Amber) -->
+  <circle cx="146" cy="140" r="6" fill="#FFC107" filter="url(#cyanGlow)" />
+</svg>
diff --git a/assets/github-app-logo.svg b/assets/github-app-logo.svg
new file mode 100644
index 00000000..d553eac1
--- /dev/null
+++ b/assets/github-app-logo.svg
@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="100%" height="100%">
+  <defs>
+    <!-- Background Gradient: Cyber Cyan to Teal Accessible -->
+    <linearGradient id="bgGradient" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#00BCD4" />
+      <stop offset="100%" stop-color="#00838F" />
+    </linearGradient>
+  </defs>
+
+  <!-- Circular Mask/Token Base -->
+  <circle cx="128" cy="128" r="128" fill="url(#bgGradient)" />
+
+  <!-- Afro Base & Texture Bumps (Deep Purple) -->
+  <circle cx="128" cy="108" r="88" fill="#1A0B2E" />
+  <circle cx="64" cy="140" r="32" fill="#1A0B2E" />
+  <circle cx="192" cy="140" r="32" fill="#1A0B2E" />
+
+  <!-- Faceplate (White with Cel-shaded stroke matching the Afro) -->
+  <rect x="80" y="96" width="96" height="116" rx="48" fill="#FFFFFF" stroke="#1A0B2E" stroke-width="8" />
+
+  <!-- Visor Slot (Void) -->
+  <rect x="92" y="124" width="72" height="32" rx="16" fill="#0D0216" />
+
+  <!-- Optic Main (Neon Magenta) -->
+  <rect x="102" y="130" width="28" height="20" rx="10" fill="#E91E63" />
+  
+  <!-- Optic Secondary (Solar Amber) -->
+  <circle cx="146" cy="140" r="8" fill="#FFC107" />
+</svg>
diff --git a/docs/github-app-setup.md b/docs/github-app-setup.md
new file mode 100644
index 00000000..45acf568
--- /dev/null
+++ b/docs/github-app-setup.md
@@ -0,0 +1,47 @@
+# Fro Bot Agent — GitHub App Setup & Ownership Runbook
+
+This runbook records how the **Fro Bot Agent** GitHub App is registered and owned, and how an operator wires its credentials into their own gateway. For the public, user-facing description of the app, see [github-app.md](./github-app.md).
+
+> **Note on management:** GitHub does not reconcile App settings from a file in this repository — there is no GitOps for App configuration. This runbook is the source of truth for the App's intended configuration and for recreating it if needed.
+
+## Canonical app
+
+| Field              | Value                                                   |
+| ------------------ | ------------------------------------------------------- |
+| Name               | Fro Bot Agent                                           |
+| Owner              | the `fro-bot` GitHub account                            |
+| Public page / slug | https://github.com/apps/fro-bot-agent (`fro-bot-agent`) |
+| Permission         | `contents: read` only                                   |
+| Webhook            | none                                                    |
+| Visibility         | Public (any account can install)                        |
+
+The gateway's default install URL points at this slug (`packages/gateway/src/config.ts`). Operators pointing at a different app override it with `GATEWAY_GITHUB_APP_INSTALL_URL`.
+
+## Registering the app (one-time, GitHub UI)
+
+App registration is a manual action in the GitHub UI; it cannot be automated from this repo. The canonical app above is already registered under the `fro-bot` account. These steps are for recreating it or registering a separate app under another account.
+
+1. Go to **GitHub → Settings → Developer settings → GitHub Apps → New GitHub App** (for the account that should own it).
+2. **Name:** `Fro Bot Agent` (or your own name if registering a separate app).
+3. **Homepage URL:** the gateway repo or your deployment docs.
+4. **Webhook:** uncheck **Active** — the app needs no webhook.
+5. **Permissions → Repository → Contents:** **Read-only**. Add nothing else.
+6. **Where can this app be installed:** **Any account** (public) for the canonical app, or **Only on this account** for a private operator app.
+7. **Create GitHub App.** Note the **App ID** on the settings page.
+8. **Private keys → Generate a private key.** Save the downloaded `.pem` — this is the only copy.
+9. (Optional) Upload the avatar from `assets/github-app-logo-512.png`.
+
+## Where credentials live
+
+Credentials belong to the **operator's own gateway deployment** — never committed to this repository.
+
+| Credential        | Gateway env var          | Compose secret file                     |
+| ----------------- | ------------------------ | --------------------------------------- |
+| App ID            | `GITHUB_APP_ID`          | `deploy/secrets/github-app-id`          |
+| Private key (PEM) | `GITHUB_APP_PRIVATE_KEY` | `deploy/secrets/github-app-private-key` |
+
+The compose stack reads these via the `*_FILE` convention (`GITHUB_APP_ID_FILE`, `GITHUB_APP_PRIVATE_KEY_FILE`). See the **GitHub App** section of [`deploy/README.md`](../deploy/README.md) for the full secret-wiring walkthrough and upgrade notes.
+
+## Installing on repositories
+
+Install the app on only the repositories Fro Bot should read (least privilege), then add them from Discord with `/fro-bot add-project <repo-url>`. See [github-app.md](./github-app.md) for install/uninstall details.
diff --git a/docs/github-app.md b/docs/github-app.md
new file mode 100644
index 00000000..3d86ea7c
--- /dev/null
+++ b/docs/github-app.md
@@ -0,0 +1,78 @@
+# Fro Bot Agent — GitHub App
+
+**Fro Bot Agent** is the GitHub App that lets a self-hosted [Fro Bot](https://github.com/fro-bot/agent) Discord gateway read a repository you choose, so you can drive Fro Bot against it from Discord.
+
+- **App:** https://github.com/apps/fro-bot-agent
+- **Owner:** the `fro-bot` GitHub account
+- **Permission:** `contents: read` — read-only access to repository contents. Nothing else.
+- **Webhook:** none. The app receives no events from GitHub.
+
+## What it does
+
+When you run `/fro-bot add-project <repo-url>` in a Discord server running a Fro Bot gateway, the gateway uses this app's installation to clone and read the repository you named. The read-only `contents` permission is the entire access surface — the app cannot write to your code, open pull requests, change settings, or read anything beyond repository contents.
+
+## Permissions
+
+| Permission          | Access   | Why                                                                    |
+| ------------------- | -------- | ---------------------------------------------------------------------- |
+| Repository contents | **Read** | Clone and read the repo you explicitly add via `/fro-bot add-project`. |
+
+That is the complete list. The app requests no write scopes, no metadata beyond what `contents: read` implies, and no organization or account permissions.
+
+## Privacy
+
+The app is **inert unless you pair it with a Fro Bot gateway in your own Discord server**. Installing it grants read access; nothing happens until a gateway you control uses that access in response to a command you run.
+
+- This repository collects no data and operates no hosted service. There is no telemetry.
+- All credentials and runtime live in **your** gateway deployment, not here.
+- The app has no webhook, so GitHub sends it no events and it stores nothing on GitHub's side.
+
+## Install
+
+1. Open https://github.com/apps/fro-bot-agent and click **Install** (or **Configure**).
+2. Choose the account or organization that owns the repositories you want Fro Bot to read.
+3. Select **Only select repositories** and pick the repos you intend to add — least privilege. (You can add more later.)
+
+You only need to install on repositories you plan to use with `/fro-bot add-project`.
+
+## Uninstall
+
+Remove access at any time:
+
+1. Go to **Settings → Applications → Installed GitHub Apps** (for your account) or your org's **Settings → GitHub Apps**.
+2. Find **Fro Bot Agent** and click **Configure**.
+3. Remove individual repositories, or scroll to **Uninstall** to revoke all access.
+
+Uninstalling immediately revokes the gateway's ability to read your repositories.
+
+## Running your own gateway
+
+This app is only useful alongside a self-hosted gateway. To register your own app and wire credentials, see the [setup runbook](./github-app-setup.md).
+
+## GitHub App settings copy
+
+These values go in the App's **Basic Information** settings page (`fro-bot` account → Settings → Developer settings → GitHub Apps → Fro Bot Agent).
+
+### Description (paste into "Basic Information → Description")
+
+This field is displayed to users on the App's public page and renders markdown:
+
+```markdown
+**Fro Bot Agent** gives a self-hosted [Fro Bot](https://github.com/fro-bot/agent) Discord gateway read-only access to repositories you choose, so you can drive Fro Bot against them from Discord.
+
+**Permission:** `contents: read` only — it can clone and read the repos you add, nothing else. No write access, no webhook.
+
+**Privacy:** inert until you pair it with a Fro Bot gateway in your own Discord server. No data is collected and no hosted service runs on your behalf; all credentials live in your own deployment.
+
+Add a repo from Discord with `/fro-bot add-project <repo-url>`.
+```
+
+### Adjacent fields
+
+- **Homepage URL:** `https://github.com/fro-bot/agent`
+- **Webhook → Active:** unchecked (the app needs no webhook)
+- **Badge background color:** `0D0216` (the Void brand color — frames the cyan token on near-black)
+
+### Short blurb (for any one-line listing)
+
+> Read-only repo access for your self-hosted Fro Bot Discord gateway — no webhook, inert until you use it.