docs(use-ai): document cycling animation symptom for BYOK OpenAI rate limits

[george-dilthey]

What changed

Added a new troubleshooting section to docs/use-ai-integration-overview.md explaining that Claygent and Use AI cells display the cycling animation text ("Orchestrating...", "Polishing...", "Calibrating...", etc.) while waiting for OpenAI rate limits to reset — making the rate limit condition visually indistinguishable from normal active processing. The section explains the 1-hour retry window before the "Rate limit wait time exceeded" error appears, and provides resolution steps (switch to Clay's managed account, or upgrade the OpenAI usage tier). Also references the Stop button for stopping a run in progress.

Why

Intercom conversation #215475004701179: a customer (Quinton Hollenbach, We Are Globex) reported their column using a personal OpenAI API key "keeps spinning" with no progress and couldn't stop it. Fin escalated to a human (support admin Jon Rene) who diagnosed OpenAI Usage Tier 1 rate limits as too low for Claygent's request volume.

The existing docs cover the end states (warning icons, "Rate limit wait time exceeded" error) but not the intermediate state the customer actually saw: cells showing cycling animation words indefinitely with 0% table progress, before any explicit error appears. A customer searching for "cells stuck on Orchestrating" or "column spinning with no progress" would not find the existing rate-limit section because it's titled with the error message, not the visual symptom.

The new section uses the customer's vocabulary ("spinning", "keeps spinning") and describes the exact visual symptom.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/apps/w28k1kwz/conversations/215475004701179
• Screenshots from conversation: cells showing "Orchestrating...", "Polishing...", "Calibrating..." etc. at 0% progress
• Code: apps/frontend/src/components/fields/types/action/AICyclingConstants.ts — confirms "Orchestrating...", "Polishing...", etc. are animation words for AI cells in any processing state
• Code: apps/frontend/src/components/fields/types/action/CellViewer.tsx:156–161 — confirms cycling animation appears for any isInProgress state (including RATE_LIMITED) for Claygent/Use AI columns
• Code: libs/shared-backend/src/services/ai-runner-client.ts:13 — MAX_TASK_WAIT_TIME_MS = 60 * 60 * 1000 (1 hour retry window before error)
• Code: libs/shared-backend/src/ratelimit/throttling.ts:366–391 — retry with backpressure for up to 1 hour before surfacing ERROR_RATE_LIMIT_MAX_WAIT_TIME_EXCEEDED
• Verifier sub-agent: cycling animation for RATE_LIMITED cells (PASS), 1-hour retry window (PASS), BYOK available to all customers (PASS)

Uncertainties

None. All behavioral claims verified against code via the verifier sub-agent (two rounds).

Related observations

The human support agent in the ticket recommended switching to "GPT-3.5 Turbo" as a workaround — this model has been removed from Clay (mapped to gpt-4o-mini per backfill-preset-use-ai-model-name.ts:36). The agent's suggestion was technically incorrect. The ticket was also initially classified as a credit refund request but reclassified to "Other / Not a Billing Issue" — rate-limited cells receive credits refunded per CreditRefundRules.ts:11.

Closes DOC-1075

[linear-code]

DOC-1075