feat(ai): Phase 1 — provider configuration, installer step, admin + company settings

Foundation for the AI chatbot + text generation feature. Phase 1 is infrastructure only: driver plumbing, configuration storage with encrypted API keys, global vs per-company resolution, admin + company UI pages, and an optional installer wizard step. The chat assistant and text-generation WYSIWYG integration come in later phases.

**Driver plumbing (app/Support/Ai/)** — AiDriver abstract, AiDriverFactory, AiException, AiChatResponse DTO, OpenRouterDriver concrete implementation. OpenRouter is the OpenAI-compatible aggregator that unlocks hundreds of models behind one API key and one request shape — ideal as the default v1 driver. Drivers are extensible the same way exchange rate drivers are: the module Registry's generic registerDriver('ai', ...) machinery plus a typed Registry::registerAiDriver() convenience wrapper (shipped in the upstream invoiceshelf/modules package in a paired commit).

**AiConfigurationService** — mirrors MailConfigurationService shape but with one deliberate deviation: API keys are encrypted at the service layer via Crypt::encryptString before persistence. OpenRouter bearer tokens have much bigger blast radius than SMTP passwords. Same settings / company_settings tables, same global-vs-per-company pattern, same use_custom_ai_config override toggle. Resolution order: global ai_enabled must be YES, then the company either overrides via use_custom_ai_config=YES (and can opt out with ai_enabled=NO inside the override) or inherits the global config.

**Controllers** — Admin/Settings/AiConfigurationController (global CRUD + driver list + test connection), Company/Settings/CompanyAiConfigurationController (per-company override + test), Setup/AiConfigurationController (installer wizard step, skippable with explicit ai_enabled=NO). API key is always masked as '********' in GET responses — the frontend submits the placeholder back on save and the backend preserves the stored value.

**Installer wizard** — new optional step 7 'AI' between Mail and Account. Default OFF with a Skip button. MailView.vue now routes to installation.ai instead of installation.account; installation.ai then routes to installation.account. Step order comment updated in routes.ts.

**Admin + Company settings pages** — AdminAiConfigView (no toggle, always global) and AiConfigView (with use_custom_ai_config BaseSwitchSection that auto-saves OFF). Both share AiConfigurationForm which renders the driver selector, API key input with show/hide, driver-specific config_fields (base_url for OpenRouter), and per-role enable toggles with free-text model inputs backed by a datalist of suggested models from driver metadata.

**Bootstrap endpoint** — adds an ai block to the response: { enabled, chat_enabled, text_generation_enabled }. All three are booleans resolved through AiConfigurationService::resolveForCompany(). Never leaks the API key. Frontend feature flags read from bootstrapData.ai to decide whether to show Phase 2/3 UI.

**Bouncer ability** 'manage ai config' added to SettingsPolicy, gated on isSuperAdmin() (same pattern as manage email config, manage pdf config).

**Tests** (22 new) — Unit: AiDriverFactory resolves built-in + Registry-contributed drivers, rejects unknown, merges availableDrivers. AiConfigurationService: encryption round-trip, resolution order (3 cases: global off, inherit global, override with company key, override with opt-out), makeDriver null/instance cases, listDrivers metadata. Feature: admin save + read with api key masking, preserve-on-placeholder behavior, company toggle ON/OFF semantics, bootstrap ai flags reflect resolution, company opt-out path.

372 tests pass (was 350, +22). Pint clean. npm run build clean. Phase 2 (chat assistant + tool calling) and Phase 3 (WYSIWYG text generation popup) are separate follow-up commits — this one is the foundation only.

resources/scripts/api/endpoints.ts

@@ -115,6 +115,18 @@ export const API = {
   COMPANY_MAIL_CONFIG: '/api/v1/company/mail/company-config',
   COMPANY_MAIL_TEST: '/api/v1/company/mail/company-test',
 
+  // AI Configuration (global)
+  AI_DRIVERS: '/api/v1/ai/drivers',
+  AI_CONFIG: '/api/v1/ai/config',
+  AI_TEST: '/api/v1/ai/test',
+
+  // Company AI Configuration
+  COMPANY_AI_CONFIG: '/api/v1/company/ai/config',
+  COMPANY_AI_TEST: '/api/v1/company/ai/test',
+
+  // Installer AI Configuration
+  INSTALLATION_AI_CONFIG: '/api/v1/installation/ai/config',
+
   // PDF Configuration
   PDF_DRIVERS: '/api/v1/pdf/drivers',
   PDF_CONFIG: '/api/v1/pdf/config',

resources/scripts/api/services/ai.service.ts

@@ -0,0 +1,51 @@
+import { client } from '../client'
+import { API } from '../endpoints'
+import type {
+  AiConfig,
+  AiDriversResponse,
+  AiTestPayload,
+  AiTestResponse,
+  CompanyAiConfig,
+} from '@/scripts/types/ai-config'
+
+export const aiService = {
+  // Driver catalog — same shape across admin, company, installer contexts.
+  async getDrivers(): Promise<AiDriversResponse> {
+    const { data } = await client.get(API.AI_DRIVERS)
+    return data
+  },
+
+  // --- Global (admin) ---
+
+  async getGlobalConfig(): Promise<AiConfig> {
+    const { data } = await client.get(API.AI_CONFIG)
+    return data
+  },
+
+  async saveGlobalConfig(payload: AiConfig): Promise<{ success?: string; error?: string }> {
+    const { data } = await client.post(API.AI_CONFIG, payload)
+    return data
+  },
+
+  async testGlobalConnection(payload: AiTestPayload): Promise<AiTestResponse> {
+    const { data } = await client.post(API.AI_TEST, payload)
+    return data
+  },
+
+  // --- Per-company ---
+
+  async getCompanyConfig(): Promise<CompanyAiConfig> {
+    const { data } = await client.get(API.COMPANY_AI_CONFIG)
+    return data
+  },
+
+  async saveCompanyConfig(payload: CompanyAiConfig): Promise<{ success?: boolean; error?: string }> {
+    const { data } = await client.post(API.COMPANY_AI_CONFIG, payload)
+    return data
+  },
+
+  async testCompanyConnection(payload: AiTestPayload): Promise<AiTestResponse> {
+    const { data } = await client.post(API.COMPANY_AI_TEST, payload)
+    return data
+  },
+}

resources/scripts/api/services/bootstrap.service.ts

@@ -29,6 +29,11 @@ export interface BootstrapResponse {
   config: Record<string, unknown>
   global_settings: Record<string, string>
   modules: string[]
+  ai?: {
+    enabled: boolean
+    chat_enabled: boolean
+    text_generation_enabled: boolean
+  }
   user_menu?: Array<{ title: string; link: string; icon: string; priority: number; name: string }>
   admin_mode?: boolean
   pending_invitations?: Array<{