@hasna/connectors 0.2.6 → 0.2.8

package/connectors/connect-github/CLAUDE.md

@@ -47,12 +47,42 @@ src/
 └── index.ts       # Library exports
 ```
 
-## Authentication
+## Authentication (2025+)
 
-Bearer Token authentication. Credentials can be set via:
+Bearer Token authentication. Use **fine-grained PATs** (GA since March 2025) for all new projects — they are now the recommended token type.
+
+Credentials can be set via:
 - Environment variable (see below)
 - Profile configuration: `connect-github config set-key <key>`
 
+### Token Types
+
+| Type | Recommendation |
+|------|---------------|
+| Fine-grained PAT | **Preferred** — GA since March 2025, granular permissions, audit-log `token_id` tracking |
+| Classic PAT | Legacy — still works, but over-permissioned |
+
+Fine-grained PAT gaps (not yet supported): Packages API, Checks API, internal repos outside target org, multi-org access.
+
+### Required Scopes (fine-grained PAT)
+
+- `contents:read/write` — repos, files
+- `issues:read/write` — issues, comments
+- `pull_requests:read/write` — PRs, reviews
+- `metadata:read` — required for all repo access
+- `models:read` — if using GitHub Models API (required since March 29 2025)
+
+### API Version
+
+Current: `X-GitHub-Api-Version: 2022-11-28` (unchanged)
+
+### GitHub MCP Server
+
+The Remote GitHub MCP Server is GA since September 2025. Add to your MCP config:
+```json
+{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }
+```
+
 
 ## Key Patterns
 

package/connectors/connect-gmail/CLAUDE.md

@@ -47,6 +47,28 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2025-2026)
+
+### OAuth Enforcement (May 2025)
+Google fully enforced OAuth 2.0 for all Gmail access as of May 2025. Less Secure Apps / password-based auth is permanently disabled. All clients MUST use OAuth 2.0 token-based authentication.
+
+### Scope Classification (2026)
+| Scope | Classification | Notes |
+|-------|---------------|-------|
+| `https://mail.google.com/` | Restricted | Full access |
+| `https://www.googleapis.com/auth/gmail.modify` | Restricted | Read + modify |
+| `https://www.googleapis.com/auth/gmail.readonly` | Restricted | Read only |
+| `https://www.googleapis.com/auth/gmail.send` | Sensitive | Send only |
+| `https://www.googleapis.com/auth/gmail.metadata` | Non-sensitive | Headers only |
+
+Restricted scopes require Google's restricted scope verification process including a third-party security assessment. For send-only use cases, prefer `gmail.send` to avoid stricter compliance requirements.
+
+### Gmail Postmaster Tools API v2 (GA Feb 2026)
+New: `POST /v2/domains/{domain}:queryDomainStats` — flexible querying of domain stats including compliance status. Supports batch operations. The v2beta endpoint was available Dec 2025.
+
+### Deal Cards in Promotions Tab (Sep 2025)
+New annotation support for creating Deal Cards. See Gmail annotations documentation.
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-google/CLAUDE.md

@@ -47,6 +47,17 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Auth Notes (2026)
+
+Google OAuth 2.0 — use Application Default Credentials or service account JSON.
+
+### Maps Platform Client IDs Deprecated (May 2025+)
+Maps platform client IDs deprecated May 26, 2025, cannot be used after May 31, 2026.
+- In Apps Script: `setAuthentication(clientId, signingKey)` → deprecated Jun 2026
+- Use `setAuthenticationByKey(apiKey)` or `setAuthenticationByKey(apiKey, signingKey)` instead
+
+OAuth scopes are unchanged. userinfo endpoint: `https://www.googleapis.com/oauth2/v3/userinfo`
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-googlecalendar/CLAUDE.md

@@ -47,6 +47,15 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2026)
+
+### Google Meet Conference Guidance (Feb 2026)
+Do NOT reuse Google Meet codes across different calendar events — causes access issues and exposes meeting details to unintended users.
+Always generate a new conference using the `createRequest` field for every new event:
+```json
+"conferenceData": { "createRequest": { "requestId": "unique-id", "conferenceSolutionKey": { "type": "hangoutsMeet" } } }
+```
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-googlecloud/CLAUDE.md

@@ -47,6 +47,18 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Auth Notes (2026)
+
+### Recommended Auth Methods
+1. **Application Default Credentials (ADC)** — `GOOGLE_APPLICATION_CREDENTIALS` env var pointing to service account JSON
+2. **Service Account Key** — JSON key file with email + private key
+3. **Workload Identity Federation** — keyless auth from AWS/Azure/on-prem (recommended for production)
+4. **OAuth 2.0 User Credentials** — for user-delegated access
+
+### Google AI / Gemini (separate from GCP)
+- Gemini API: `GEMINI_API_KEY` — simpler for Gemini models
+- Vertex AI: uses ADC or service account — more enterprise controls
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-googlecontacts/CLAUDE.md

@@ -47,6 +47,13 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Notes (2026)
+
+Use **Google People API** (not deprecated Contacts API v3).
+Base URL: `https://people.googleapis.com/v1/`
+Key endpoints: `/people/me`, `/people:listDirectoryPeople`, `/people:batchGet`
+Scopes: `contacts`, `contacts.readonly`, `directory.readonly`, `user.addresses.read`, `user.emails.read`
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-googledocs/CLAUDE.md

@@ -47,6 +47,13 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2026)
+
+### Gemini Features (Feb 2026)
+Audio summaries now available in Google Docs — Gemini-powered feature that generates audio overviews of documents.
+
+No breaking API changes to the Docs API v1 (stable).
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-googledrive/CLAUDE.md

@@ -47,6 +47,11 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2026)
+
+### Deprecation (Feb 2026)
+`enforceExpansiveAccess` query parameter is now deprecated for all methods in the permissions resource (v2 and v3). To restrict item access, use **folders with limited access** setting instead.
+
 ## Authentication
 
 OAuth authentication (Google OAuth2). Credentials can be set via:

package/connectors/connect-googlegemini/CLAUDE.md

@@ -47,6 +47,24 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Models (2026)
+
+| Model | Description |
+|-------|-------------|
+| `gemini-3.1-pro-preview` | Latest (Feb 2026), #1 on 13/16 benchmarks, 1M ctx — **use for complex tasks** |
+| `gemini-3.1-pro-preview-customtools` | Agent workflows with custom tools (bash, code, multi-step) |
+| `gemini-3.1-flash-lite` | Fast, budget-friendly (preview) |
+| `gemini-3-pro-preview` | Gemini 3 Pro |
+| `gemini-3-flash-preview` | Frontier performance at fraction of cost |
+| `gemini-2.5-pro` | GA, advanced reasoning (discontinues Jun 17 2026) |
+| `gemini-2.5-flash` | Best price-performance, GA |
+| `gemini-2.5-flash-lite` | Fastest, most budget-friendly |
+| `gemini-2.5-flash-live-preview` | Real-time audio/video Live API |
+
+For image gen (Nano Banana): `gemini-2.5-flash-preview-image-generation`
+For video gen (Veo): `veo-3.1-generate-preview`
+For TTS: `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-googlegemini/src/types/index.ts

@@ -2,19 +2,26 @@
 
 // ============ Models ============
 export type GeminiModel =
-  // Text Generation Models
+  // Gemini 3.1 (Feb 2026, latest)
+  | 'gemini-3.1-pro-preview'            // Most advanced, tops 13/16 benchmarks
+  | 'gemini-3.1-pro-preview-customtools' // Agent/tool-use optimized variant
+  | 'gemini-3.1-flash-lite'             // Fast, cost-efficient (preview)
+  // Gemini 3 (2025-2026)
   | 'gemini-3-pro-preview'
   | 'gemini-3-flash-preview'
+  // Gemini 2.5 (GA)
   | 'gemini-2.5-pro'
   | 'gemini-2.5-flash'
   | 'gemini-2.5-flash-lite'
-  // Image Generation Models (Nano Banana)
+  // Image Generation (Nano Banana)
   | 'gemini-2.5-flash-preview-image-generation'
   | 'gemini-3-pro-image-preview'
   // TTS Models
   | 'gemini-2.5-flash-preview-tts'
   | 'gemini-2.5-pro-preview-tts'
-  // Embedding Model
+  // Live API (real-time audio/video)
+  | 'gemini-2.5-flash-live-preview'
+  // Embedding
   | 'gemini-embedding-001'
   // Legacy
   | 'gemini-2.0-flash'

package/connectors/connect-googlemaps/CLAUDE.md

@@ -47,6 +47,21 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2025-2026)
+
+### Places API v2 (New)
+New Places API (v2) is preferred over legacy Places API (v1). Use `https://places.googleapis.com/v1/places` endpoints.
+
+### Client IDs Deprecated (May 2025 → May 2026)
+Maps Platform client IDs deprecated May 26, 2025. Cannot be used after May 31, 2026.
+Use API key authentication exclusively.
+
+### Current APIs
+- Places API (New): `https://places.googleapis.com/v1/`
+- Routes API: `https://routes.googleapis.com/`
+- Geocoding API: `https://maps.googleapis.com/maps/api/geocode/json`
+- Maps JavaScript API, Street View, Distance Matrix, etc.
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-googlesheets/CLAUDE.md

@@ -47,6 +47,16 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2025)
+
+### Tables API (Apr 2025)
+Create, modify, and take basic actions on Tables in Google Sheets:
+- `addTable` request in `batchUpdate`
+- `Table` object in Sheets API
+
+### Smart Chips (Jun 2025)
+Create, update, and read Google Drive and People chips via the Sheets API.
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-googletasks/CLAUDE.md

@@ -47,6 +47,12 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Notes (2026)
+
+Google Tasks API v1 is stable. Base URL: `https://tasks.googleapis.com/tasks/v1/`
+Key endpoints: `/lists`, `/lists/{list}/tasks`, `/users/@me/lists`
+Required scope: `https://www.googleapis.com/auth/tasks`
+
 ## Authentication
 
 OAuth authentication. Credentials can be set via:

package/connectors/connect-hedra/CLAUDE.md

@@ -47,6 +47,21 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API (Full Platform, Feb 2026)
+
+Full Hedra API launched Feb 2026. All models available programmatically.
+
+New API endpoints (unified):
+- `GET /models` — list models
+- `POST /assets/generate` — generate image/video/avatar
+- `GET /assets/{id}` — check status
+- `GET /credits` — credit balance
+
+Legacy Character-2 API: `POST /v1/characters` (still works)
+Auth: `X-API-Key` header
+
+Capabilities: image generation, video generation, avatar generation, Live Avatar (real-time).
+
 ## Authentication
 
 Bearer Token authentication. Credentials can be set via:

package/connectors/connect-heygen/CLAUDE.md

@@ -47,6 +47,20 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2025-2026)
+
+### Avatar IV Endpoint (Jan 2026)
+```
+POST /v2/video/av4/generate
+```
+Photorealistic full-body avatar videos. Speed/quality mode selection.
+
+### Template API Variables (Aug 2025)
+AI Studio templates now support API creation with variable customization: avatars, text, elements, scene scripts.
+
+### Digital Twin — Avatar IV (Aug 2025)
+Full-body digital twins with gestures and emotion.
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-huggingface/CLAUDE.md

@@ -47,6 +47,26 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Updates (2025-2026)
+
+### Serverless Inference API — Overhauled (2026)
+The Serverless Inference API is being completely overhauled. Key changes:
+
+New router endpoint pattern:
+```
+https://router.huggingface.co/hf-inference/models/{model}/v1/chat/completions
+```
+
+For chat completions (OpenAI-compatible):
+```bash
+curl -X POST https://router.huggingface.co/hf-inference/models/meta-llama/Llama-3.1-8B-Instruct/v1/chat/completions \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct", "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+Note: Error responses may return HTML 503 during migration period — handle non-JSON responses gracefully.
+
 ## Authentication
 
 Bearer Token authentication. Credentials can be set via:

package/connectors/connect-icons8/CLAUDE.md

@@ -47,6 +47,12 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Notes (2026)
+
+Icons8 API: `https://api.icons8.com/api/iconsets/v5/`
+Key endpoints: `/search`, `/icon`, `/categories`, `/styles`
+Auth: `token` query parameter
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-maropost/CLAUDE.md

@@ -47,6 +47,12 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Notes (2026)
+
+Maropost Marketing Cloud API: `https://api.maropost.com/accounts/{account_id}/`
+Auth: `auth_token` query parameter or Bearer token header.
+Key resources: contacts, campaigns, tags, lists, journeys, reports.
+
 ## Authentication
 
 Bearer Token authentication. Credentials can be set via:

package/connectors/connect-mercury/CLAUDE.md

@@ -47,6 +47,20 @@ src/
 └── index.ts       # Library exports
 ```
 
+## New Endpoints (2025-2026)
+
+Mercury has been rapidly expanding their API. Recent additions:
+- **Webhooks** — real-time HTTP notifications for account events (transactions, etc.)
+- **Internal Transfers** — `POST /transfer` — move money between accounts (requires `SendMoney` write scope)
+- **Users API** — `GET /api/v1/users` — retrieve organization users
+- **Account Balance Events** — webhooks/events for balance change notifications
+- **SAFE API** — 3 new endpoints for reading SAFE (Simple Agreement for Future Equity) data
+- **Treasury API statements** — programmatic statement retrieval
+- **Attachment uploads** — upload attachments to transactions and recipients
+
+Auth: Basic auth (API token as username, empty password) or Bearer token.
+Token tiers: Read-only, Read-write (requires IP whitelist), Custom (scoped).
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-meta/CLAUDE.md

@@ -47,6 +47,22 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Graph API Updates (2025-2026)
+
+### Current Version: v24.0 (Oct 2025)
+
+### Breaking Changes in v24.0
+- **Advantage+ Shopping/App campaigns**: Cannot be created/updated via API from v24.0 (Feb 2025). Extends to ALL versions by May 19, 2026. Migrate to new Automation Unification workflow.
+- **Customer file custom audiences**: Flagged audiences fail to update (effective Jan 6, 2026 for all versions)
+- **Certificate Transparency**: All endpoints/webhooks removed (Oct 17, 2025)
+- **Live Video API**: `overlay_url` field removed
+- **Messenger lead ads**: Cannot create lead ads that generate leads in Messenger via API
+
+### Upcoming Changes (by Jun 2026)
+- **Page Viewer Metric**: Replaces legacy reach metric — consistent cross-platform measurement (Facebook + Instagram)
+- **Retiring**: Post/Page Reach, Video Impressions, Story Impressions metrics
+- **Webhook permissions**: Updates coming
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-midjourney/CLAUDE.md

@@ -47,6 +47,13 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Status (2026) — Important
+
+No official public API. The official API is only available to Enterprise subscribers.
+- Official API: `https://api.midjourney.com/v2` with Bearer token (Enterprise only)
+- Current model: **v8** (2026) — text rendering, video gen (10s/60fps), 3D export, `--cref`
+- Unofficial third-party wrappers (Apiframe, TTAPI) available but may violate ToS
+
 ## Authentication
 
 Bearer Token authentication. Credentials can be set via:

package/connectors/connect-mistral/CLAUDE.md

@@ -47,6 +47,26 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Models (2026)
+
+| Model | Description |
+|-------|-------------|
+| `mistral-large-latest` | Large 3 (Dec 2025), top-tier |
+| `mistral-medium-latest` | Medium 3.1 (Aug 2025), multimodal — **recommended default** |
+| `magistral-medium-latest` | Magistral 1.2 (Sep 2025), reasoning + vision, 40K ctx |
+| `codestral-latest` | Codestral 2508, code specialist, 256K context |
+| `devstral-latest` | Devstral Medium, coding agents, multi-file editing |
+| `ministral-8b-latest` | Edge model, fast and cheap |
+| `ministral-3b-latest` | Fastest edge model |
+
+New capabilities (2025-2026):
+- **OCR / Document AI**: `mistral-ocr-2512` via `POST /v1/ocr`
+- **Audio transcription**: `voxtral-mini-2602` via `POST /v1/audio/transcriptions` (with diarize, context biasing)
+- **Reasoning**: Magistral series with extended thinking
+- **Coding agents**: Devstral for multi-file codebase exploration
+
+Default: `mistral-medium-latest`
+
 ## Authentication
 
 Bearer Token authentication. Credentials can be set via:

package/connectors/connect-mistral/src/types/index.ts

@@ -5,26 +5,61 @@ export interface MistralConfig {
   baseUrl?: string;
 }
 
-// Models
+// Models (2026)
 export type MistralModel =
-  | 'mistral-large-latest'
+  // Latest aliases (always point to newest)
+  | 'mistral-large-latest'     // → mistral-large-2512
+  | 'mistral-medium-latest'    // → mistral-medium-2508
   | 'mistral-small-latest'
-  | 'codestral-latest'
+  | 'codestral-latest'         // → codestral-2508
+  | 'magistral-medium-latest'  // → magistral-medium-2509
   | 'ministral-8b-latest'
   | 'ministral-3b-latest'
-  | 'open-mistral-nemo'
-  | 'pixtral-large-latest';
+  | 'pixtral-large-latest'
+  | 'devstral-latest'
+  // Pinned versions (2025-2026)
+  | 'mistral-large-2512'       // Mistral Large 3 (Dec 2025)
+  | 'mistral-medium-2508'      // Mistral Medium 3.1 (Aug 2025)
+  | 'mistral-medium-2505'      // Mistral Medium 3 (May 2025)
+  | 'magistral-medium-2509'    // Magistral Medium 1.2 (Sep 2025, reasoning)
+  | 'magistral-medium-2507'    // Magistral Medium 1.1
+  | 'magistral-medium-2506'    // Magistral Medium 1.0
+  | 'magistral-small-2509'     // Magistral Small 1.2
+  | 'codestral-2508'           // Codestral (Jul 2025, 256K context)
+  | 'codestral-2501'
+  | 'devstral-medium-2507'     // Devstral (coding agents)
+  | 'ministral-3b-2512'
+  | 'ministral-8b-2512'
+  | 'ministral-14b-2512'
+  | 'ministral-3b-2410'
+  | 'ministral-8b-2410'
+  | 'open-mistral-nemo';
 
 export type MistralEmbeddingModel = 'mistral-embed';
 
+export type MistralOCRModel = 'mistral-ocr-2512' | 'mistral-ocr-2505';
+
+export type MistralAudioModel = 'voxtral-mini-2602' | 'voxtral-mini-transcribe-realtime-2602' | 'voxtral-mini-2507';
+
 export const MISTRAL_MODELS: MistralModel[] = [
+  // Latest aliases
   'mistral-large-latest',
+  'mistral-medium-latest',
   'mistral-small-latest',
   'codestral-latest',
+  'magistral-medium-latest',
   'ministral-8b-latest',
   'ministral-3b-latest',
-  'open-mistral-nemo',
   'pixtral-large-latest',
+  'devstral-latest',
+  // Pinned versions
+  'mistral-large-2512',
+  'mistral-medium-2508',
+  'magistral-medium-2509',
+  'codestral-2508',
+  'devstral-medium-2507',
+  'ministral-14b-2512',
+  'open-mistral-nemo',
 ];
 
 // Chat Completions
@@ -156,7 +191,7 @@ export interface EmbeddingOptions {
   model?: MistralEmbeddingModel | string;
 }
 
-export const DEFAULT_CHAT_MODEL: MistralModel = 'mistral-small-latest';
+export const DEFAULT_CHAT_MODEL: MistralModel = 'mistral-medium-latest';
 export const DEFAULT_EMBEDDING_MODEL: MistralEmbeddingModel = 'mistral-embed';
 
 // Common types

package/connectors/connect-mixpanel/CLAUDE.md

@@ -47,6 +47,17 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Notes (2026)
+
+Base URLs:
+- Ingestion: `https://api.mixpanel.com/`
+- Query (EU): `https://eu.mixpanel.com/api/query/`
+
+Auth: Service Account credentials (username:password as HTTP Basic Auth) for Query API. Project token for Ingestion API.
+
+Key endpoints: `/track` (events), `/engage` (user profiles), `/groups` (group analytics), `/import` (batch import).
+Query API: `/segmentation`, `/funnel`, `/retention`, `/events`.
+
 ## Authentication
 
 API Key authentication. Credentials can be set via:

package/connectors/connect-notion/CLAUDE.md

@@ -56,6 +56,36 @@ src/
 └── index.ts       # Library exports
 ```
 
+## API Version (2026) — BREAKING CHANGES
+
+### Current Version: `2026-03-11`
+Set header: `Notion-Version: 2026-03-11`
+SDK: upgrade to `@notionhq/client` v5.12.0+
+
+### Breaking Changes in `2026-03-11`
+
+| Change | Old (`2025-09-03`) | New (`2026-03-11`) |
+|--------|-------------------|-------------------|
+| Block positioning | `after: "block-id"` string | `position: { type: "after_block", after_block: { id: "..." } }` |
+| Trash status | `archived: true/false` | `in_trash: true/false` |
+| Block type | `transcription` | `meeting_notes` |
+
+#### 1. Replace `after` → `position` (Append Block Children)
+```json
+// NEW: PATCH /v1/blocks/{id}/children
+{ "position": { "type": "after_block", "after_block": { "id": "b5d8fd79-..." } }, "children": [...] }
+// position types: "after_block", "start", "end"
+```
+
+#### 2. Replace `archived` → `in_trash`
+```json
+// NEW: PATCH /v1/pages/{id}
+{ "in_trash": true }
+```
+Applies to pages, databases, blocks, and data sources in both requests AND responses.
+
+#### 3. Replace `transcription` → `meeting_notes` block type
+
 ## Authentication
 
 Two authentication methods supported:

package/connectors/connect-openai/AGENTS.md

@@ -6,6 +6,21 @@ This file provides guidance to AI coding agents when working with this repositor
 
 connect-openai is a TypeScript CLI and library for OpenAI's API. It provides chat completions, embeddings, and image generation with multi-profile support.
 
+## Models (2026)
+
+| Model | Description |
+|-------|-------------|
+| `gpt-5.4` | Latest, most capable |
+| `gpt-4.1-mini` | Fast, cheap — **use as default** |
+| `gpt-4.1` | High capability |
+| `o3` | Advanced reasoning |
+| `o4-mini` | Fast reasoning |
+| `gpt-image-1` | Image generation (preferred over DALL-E 3) |
+
+Default: `gpt-4.1-mini`
+
+Note: GPT-4o, GPT-4.1, o4-mini retired from **ChatGPT** Feb 2026 — still available in API.
+
 ## Build & Run Commands
 
 ```bash

package/connectors/connect-openai/CLAUDE.md

@@ -47,6 +47,29 @@ src/
 └── index.ts       # Library exports
 ```
 
+## Models (2026)
+
+| Model | Description |
+|-------|-------------|
+| `gpt-5.4` | Latest GPT-5, most capable |
+| `gpt-5.2` / `gpt-5.1` | GPT-5 variants |
+| `gpt-4.1` | High-capability, cost-effective |
+| `gpt-4.1-mini` | Fast and cheap — **recommended default** |
+| `gpt-4o` | Still supported in API (retired from ChatGPT Feb 2026) |
+| `o4-mini` | Reasoning model, fast |
+| `o3` | Advanced reasoning |
+| `gpt-image-1` | Native image generation (replaces DALL-E 3 for new projects) |
+
+Default: `gpt-4.1-mini`
+
+## Responses API (2025+)
+
+For agentic use cases, prefer the **Responses API** over Chat Completions:
+- Built-in tools: file search, code interpreter, image generation, MCP support
+- Stateful conversations
+- Endpoint: `POST /v1/responses`
+- Use Chat Completions for simple text generation; Responses API for agents
+
 ## Authentication
 
 Bearer Token authentication. Credentials can be set via: