# Discord Bot Connector

## What It Does
Gipity runs a public Discord server where anyone types `/build <prompt>` and watches Gip build and deploy a real app to a live URL, in public — the Midjourney `/imagine` model. The prompt, a progress card, and the final **Open App** link post in the shared showcase channel; the detailed build log streams in a public thread attached to that message. Every build produces a shareable `app.gipity.ai/<user>/<project>/` link.

## How Users Connect

**New users (no Gipity account):**
1. Join the Gipity Discord server and go to the showcase channel
2. Type `/build <what you want>` (e.g. `/build a snake game with a leaderboard`)
3. Accept the Terms of Service the first time (a one-time Accept/Decline prompt) — a Gipity account is created automatically and the build you just asked for starts immediately, no need to re-type it

Each `/build` opens its own thread and its **own new project**, so one build never overwrites another. When the app deploys, the builder also gets a private DM with the live link and an **Open in editor** button.

**Claim your account (to edit on the web):**
- Click **Open in editor** in the DM, or use **Log in with Discord** on the Gipity web app
- You land in the exact account your Discord identity built — keyed on your verified Discord id, never on email, so nobody can claim someone else's account
- Claiming restores the normal 5-hour free-credit refresh (anonymous bot users refresh every 30 days until claimed)

**Existing web users (link Discord to your account):**
1. Ask the agent "connect my Discord" (or use the `connector_manage` connect action for `discord`) to get a one-time token
2. Run `/link token:<token>` as a slash command in the Gipity Discord server

**Disconnect:**
- Ask the agent "disconnect Discord", or use `connector_manage` disconnect with provider `discord`

## Auto-Provisioning
When a Discord user first accepts ToS and builds:
- A Gipity account is created with a synthetic email (`discord-{id}@connector.gipity.ai`)
- A default agent, initial free credits, and a **30-day** free-refresh interval are granted (vs the usual 5h; cleared to 5h once the account is claimed)
- A new project + conversation is created **per build thread**

## What Works in Discord
- **`/build <prompt>`** — full chat/agent loop with the build log streaming into a thread (progressive edits)
- **Image & audio generation** — posted as attachments in the thread
- **Code execution, web search, Twitter search** — results in the thread
- **App deployment** — the public channel card updates with an **Open App** button; the builder is DM'd the link + **Open in editor**
- **Log in with Discord** — a first-class web sign-in method and the connector account claim

## Limitations
- **Slash-command driven** — iterate by running `/build` again in the same thread (plain-text in-thread iteration needs the Message Content intent, not enabled at launch)
- **No destructive confirmations** — operations like DROP TABLE or recursive delete are auto-skipped (users are directed to the web editor)
- **Message length** — Discord caps messages at 2000 characters; long responses are split automatically
- **Deploy target** — connector builds deploy to dev by default
- **Anonymous rate** — free plan with a 30-day refresh until the account is claimed

## For Users Asking About Discord
If a user asks "how do I use Gipity on Discord?", tell them:
1. Join the Gipity Discord server
2. Type `/build <your idea>` in the showcase channel and accept the Terms of Service
3. Watch it build in a thread; open the live link; DM has an **Open in editor** button to claim/edit on the web

To link an existing web account, use the `connector_manage` tool with action "connect" and provider "discord" to generate a one-time token, then run `/link token:<token>` in Discord. To disconnect, use `connector_manage` with action "disconnect" and provider "discord".

## Technical Details (For Reference)
- Transport: persistent `discord.js` gateway bot (posts/edits by message id via the bot token, so long builds don't hit interaction-token expiry)
- Three output surfaces: the public thread (log), the public channel card (result + Open App), and a private DM (link + Open in editor)
- Streaming: progressive thread-message editing throttled to ~1 edit/second
- Database: `connector_users` maps Discord ids to accounts; `connector_threads` maps each thread to its project + conversation
- Account claim: `oauth_identities(provider='discord')` → `connector_users(platform='discord')` → create, keyed on the verified Discord id (never the OAuth email)