Settings

Support reference for personal settings at `/settings` and organization settings at `/org-settings`.

• Personal and organization settings use the same full-height, scrollable settings shell.
• The visible content does not repeat the former large page title and description. A hidden `Settings` heading remains available to assistive technology.
• Organization settings add a compact, horizontally scrollable route navigation control above the content.

Routes

• `/settings` is the unified personal settings page.
• Legacy routes redirect to `/settings`:
• `/settings/appearance`
• `/settings/connectedAccounts`

Connected accounts

• Section title: `Connected accounts`
• Description: `Manage external accounts linked to your profile.`
• Accounts shown:
• `Gmail`
• `Telegram`
• Gmail reflects the current Google-linked profile and is display-only on this page.
• Telegram behavior:
• an unlinked account shows `Connect`
• a linked account shows its identifier and `Disconnect`
• the identifier prefers `@username`, then linked name, then the Telegram account ID
• disconnect requires confirmation in a `Disconnect Telegram` dialog
• Connecting Telegram starts with `GET /api/auth/telegram` and redirects to the returned authorization URL.
• Disconnecting uses `DELETE /api/auth/telegram`, refreshes the current user from the returned payload, and reports `Telegram account disconnected`.

Language

• Section title: `Language`
• Description: `Choose interface language.`
• Choices:
• `Automatic`
• `English`
• `Russian`
• `Spanish`
• `Ukrainian`
• `Serbian`
• `Kazakh`
• `Romanian`
• `Automatic` uses the browser's preferred language and falls back to English when that language is unsupported.

Appearance

• Theme choices:
• `Light`
• `Latte`
• `Dark`
• `Dark Blue`
• `System`
• Theme selection applies immediately.
• `Full-width AI responses` controls internal-chat presentation:
• enabled: AI responses use the full chat width
• disabled: AI responses use bubbles

• `/org-settings` redirects to `/org-settings/organization`.
• Navigation items:
• `Organization`
• `AI Providers`
• `Webchat`
• `AI Providers` and `Webchat` are visible only to org admins, owners, and developer users who pass the org-admin access check. Direct visits by other users render `AccessDenied`.
• The organization shell no longer contains the interface-language picker. Language is managed on `/settings`.
• Organization settings tabs share these initial states:
• centered `Loading` indicator while required data loads
• `Failed to load data` with `Retry` when initial loading fails
• `No organization selected` when organization context is unavailable
• Data loaded for a previous organization is discarded when the active organization changes.

• Route: `/org-settings/organization`
• Main content uses a responsive two-column card layout.

General information

• Card title: `General Information`
• Description: `Basic details about your organization`
• Fields:
• `Organization`
• `Base LLM`
• `Base LLM` lists non-realtime, non-TTS, non-STT text models from the shared model catalog.
• `Auto` clears the organization default model.
• The general Save action updates organization name and base model together.
• An empty organization name cannot be saved.
• When an AI teammate or Ally has no explicit model, runtime resolution tries the organization base model before the system fallback model.

AI teammate spending limit

• The separate `AI teammate spending limit` card applies one optional daily model-spending limit independently to every AI teammate.
• The input uses a `$` prefix and accessible label `Daily limit`.
• Valid configured values start at `$0.01` and allow at most two decimal places.
• `Remove daily limit` clears the draft to restore unlimited usage after Save.
• This card has its own Save action and reports `Daily spending limit updated` or `Failed to update daily spending limit`.
• Organization owners and admins can edit the limit. Other members see it read-only. Developer access alone does not grant edit permission.
• Route: `PUT /api/organizations/{organization_id}/ai-employee-daily-cost-limit`
• Body: `{ ai_employee_daily_cost_limit_usd: number | null }`
• The allowance resets at `00:00 UTC`. Changing or removing the limit applies immediately to usage accumulated during the current UTC day.

Debug Mode

• `Debug Mode` is an immediate-save switch.
• Description: `Enable debug mode for additional logging and diagnostics`
• Success feedback is `Debug mode enabled` or `Debug mode disabled`.

Lazy Tools

• `Lazy Tools` is an immediate-save switch.
• Description: `Load agent tools on demand instead of sending the whole tool list in every request`
• It defaults to enabled.
• When enabled, non-eager built-in and assigned MCP/OAuth tools load on demand. When disabled, those tools are exposed directly to the model.
• Feedback is `Lazy tools enabled`, `Lazy tools disabled`, or `Failed to update lazy tools`.

Auto Compacting

• `Auto Compacting` is an immediate-save switch backed by `is_auto_compacting_enabled` and defaults to disabled.
• Description: `Let agents summarise and archive their own conversation history once it outgrows the context window`
• When enabled, Alloy summarizes older conversation context after runtime limits are crossed while keeping recent messages verbatim. Summarization model usage is recorded as normal attributable usage.
• If summarization fails, Alloy keeps and sends the original history rather than dropping it.
• Feedback is `Auto compacting enabled`, `Auto compacting disabled`, or `Failed to update auto compacting`.

Organization Slack connection

• The `Slack` card manages the organization-wide Slack app used by Personal Ally.
• Description: `Interact with Ally directly in Slack`
• All organization members can see current connection information. Connect, reconnect, and disconnect require organization-admin access in both UI and backend.
• Controls:
• disconnected: `Connect`
• invalid: `Reconnect`
• active: `Disconnect`
• Active connections can show workspace name and ID, installer identity, and connection date.
• Disconnect requires entering the exact confirmation text `disconnect`.
• A successful OAuth callback returns to `/org-settings/organization?slack=connected`, reports `Connected`, and removes callback parameters from the URL.
• Connection state updates through `organization_channel_connection.updated`.
• API routes:
• `GET /api/organizations/{orgId}/slack`
• `POST /api/organizations/{orgId}/slack/oauth/start`
• `POST /api/slack/oauth/callback`
• `DELETE /api/organizations/{orgId}/slack`

Alloy API keys

• Authorized organization editors see the brand-specific API key card.
• Rows:
• `Public`
• `Private`
• The public key is displayed and can be copied.
• The private key remains masked and is fetched only when its copy action is used.

Organization data flow and permissions

• General and immediate-save settings use `PUT /api/organizations/{id}`.
• Supported page fields are `name`, `ai_default_model`, `is_debug_mode`, `use_lazy_tools`, and `is_auto_compacting_enabled`.
• The backend validates a non-null model against the model catalog and requires the lazy-tools and auto-compacting flags to be boolean.
• General editing is enabled for owners/admins and developer users through the frontend org-admin access helper. The backend independently rejects non-admin organization members.
• Organization state refreshes through `organization.updated`; reached daily-limit transitions use `ai_employee.updated`.
• Initial page rendering waits for both the model catalog and Slack connection state. `Retry` reloads both after an initial failure.
• A later model refetch failure reports `Failed to load AI models` without replacing already loaded settings content.

• Route: `/org-settings/api-keys`
• Nav label: `AI Providers`
• Main layout:
• `Provider API Keys`
• `Custom provider`
• `OpenAI Codex`
• Initial provider and Codex state is loaded before the cards render. Failure shows `Failed to load data` with `Retry`.

Manual provider keys

• Provider rows:
• `OpenAI`
• `OpenRouter`
• `Google`
• `DeepSeek`
• `Anthropic`
• Saved keys use a masked prefix/suffix preview and cannot be copied from the UI.
• Saving or clearing uses `PATCH /api/organizations/{id}/providers/{provider}` with `{ api_key: "<key>" }` or `{ api_key: null }`.
• Provider rows stay in sync through `organization_ai_provider.updated`.

Custom provider

• This is an organization-scoped OpenAI-compatible provider.
• Fields:
• `API key`
• `Base URL`
• The Base URL helper asks for the API root including any required version path and gives an example such as `https://api.example.com/v1`.
• Both fields are required before Save becomes available.
• After Save, the key uses a masked preview and the Base URL becomes read-only.
• `Reset` clears both values. The reset toast offers `Undo` for the current five-minute restore window.

OpenAI Codex

• States:
• `Connect`
• authorization with copyable `Code`, countdown, and `Open authorization page`
• active connection with `Disconnect` plus a `Details` hover card showing the Codex account `User name`, `Email`, `Connected by`, and `Connected on`
• `Disconnect` opens a `Disconnect OpenAI Codex?` confirmation dialog before revoking the connection.
• Connection attempts and provider state update in real time.
• Routes:
• `POST /api/organizations/{id}/providers/codex/connection-attempts`
• `GET /api/organizations/{id}/providers/codex/connection-attempts/current`
• `POST /api/organizations/{id}/providers/codex/revoke`

Provider runtime behavior

• Runtime uses a matching active organization provider credential before the system credential for the same provider.
• Usage with organization credentials is still recorded for usage and cost reporting but does not reduce organization `available_tokens`.
• The page listens to `organization.updated`, `organization_ai_provider.updated`, and `organization_ai_provider_connection_attempt.updated`.

• Route: `/org-settings/webchat`
• Initial loading fetches widget settings and the first webchat trigger together.
• Failure shows `Failed to load data` with `Retry`.
• Main layout uses a scrollable settings form plus `Live Preview`.
• Theme choices:
• `System`
• `Light`
• `Dark`
• `Custom`
• `System` mode has Light and Dark editing tabs.
• Color sections:
• `Minimized widget`: `Bubble color`, `Icon color`
• `Maximized widget`: `Chat background`, `Primary color`
• `Message colors`: `Customer bubble color`, `Customer text color`, `Agent bubble color`, `Agent text color`
• Each color control provides a visual picker, text value, and field-level reset.
• `Custom` mode exposes `Custom CSS` and warns that it overrides the other settings.
• Footer actions:
• `Reset to defaults`
• `Save changes`
• Backend values:
• `mode`: `system`, `light`, `dark`, `custom`
• `widgetDomain`: `default`, `proxy`
• API routes:
• `GET /api/organizations/{id}/settings/webchat-widget-settings`
• `POST /api/organizations/{id}/settings/webchat-widget-settings`
• Reset to defaults sends an empty POST body.
• Defaults can also contain runtime fields not currently editable here: `opacity`, `primaryTextColor`, `secondaryTextColor`, `borderColor`, and `systemMessageColor`.
• The preview loads the widget script, initializes it with the organization public key and first webchat trigger ID, and destroys it when leaving the page.

• Models and Voices are separate tools, not `/org-settings/*`.
• `/defaults` is the separate developer-only system defaults page.