## Context

An existing lab prototype at `/Users/pps/DEV_OLD_TEMP/lab/meta-webhooks-demo` already implements Instagram webhook handling, OAuth flow, and auto-reply. This prototype proves the core Instagram integration works. The task is to refactor it into the standardized AI Manager connector format that follows the same 4-layer architecture as existing channels (Telegram, Messenger, WhatsApp).

The Messenger connector (`@aimanager/aimanager-messenger-connector`) is chosen as the blueprint because:
- Same Meta Graph API platform as Instagram (graph.facebook.com)
- Same webhook verification pattern (hub.mode / hub.verify_token)
- Same messaging payload structure (messaging[{}] with sender/recipient/message)
- Both use OAuth + Page Access Tokens for auth
- The FacebookClient.js in Messenger can be adapted for Instagram Graph API calls

Existing lab code to reuse:
- `server/instagram-oauth.js` — full Instagram OAuth flow with 60-day tokens
- `server/instagram-reply.js` — message send/receive via Instagram Graph API
- `server/index.js` — webhook verification and handling patterns

## Goals / Non-Goals

**Goals:**
- Create the Instagram connector npm package following the `{ router, startApp }` pattern
- Implement Instagram OAuth for token management and configuration
- Handle inbound Instagram DMs (messages → AI Manager conversations)
- Handle outbound replies (AI Manager agent messages → Instagram DM)
- Add Instagram as a channel type in the Dashboard UI
- Register the connector as a server pubmodule at `/modules/instagram`

**Non-Goals:**
- Handling Instagram comments or mentions (only Direct Messages)
- Handling Instagram story mentions (out of scope for customer support)
- Media upload handling for Instagram (initial version: text only)
- 24-hour messaging window enforcement (will be handled by connector, not AI Manager)

## Decisions

### Decision: Clone Messenger connector, not Telegram
The Messenger connector shares the Meta Graph API, webhook verification, and messaging payload structure with Instagram. Telegram uses a completely different API paradigm.

### Decision: Reuse lab OAuth flow as the configuration UI
Instagram requires OAuth (not a simple bot token like Telegram). The lab's `instagram-oauth.js` provides the complete OAuth flow with 60-day token exchange and refresh. This will replace the simple "bot name + token" configure form with an OAuth-based configuration.

### Decision: Lead ID prefix: "instagram-"
Instagram users are identified by their IG user ID (numeric). The lead_id will be `instagram-{igUserId}`, parsed in the Dashboard to determine the channel type.

### Decision: No custom Helm env vars needed
Like Messenger and WhatsApp, the Instagram connector stores credentials (access token) in the MongoDB KV store via the configuration form/OAuth flow. No provider-specific env vars in Helm.

## Risks / Trade-offs

- **[24-hour reply window]** → Instagram only allows replies within 24 hours of the user's last message. The connector should detect expired windows and return a clear error.
- **[Advanced Access required]** → The `instagram_manage_messages` permission requires Meta App Review for production. Development/testing works without it.
- **[Rate limits]** → Instagram Graph API has strict rate limits (200 messages/hour per unique user). The connector should handle 429 responses gracefully.
- **[Long-lived token expiry]** → OAuth tokens expire after 60 days. The connector needs a refresh mechanism (already implemented in the lab).
- **[Instagram Business/Creator account required]** → Personal Instagram accounts cannot use the API. The connector should validate this during OAuth.