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.

app/Support/Ai/AiDriver.php

@@ -0,0 +1,85 @@
+<?php
+
+namespace App\Support\Ai;
+
+/**
+ * Abstract base for AI drivers.
+ *
+ * Concrete drivers adapt a specific AI provider (OpenRouter, Anthropic direct,
+ * local Ollama, etc.) into the two operations the host app needs:
+ *
+ *   - `chatCompletion()` — for the chat assistant. OpenAI chat format, optional
+ *     tool-calling support. Drivers MUST translate their provider's tool-call
+ *     shape into the OpenAI-style `tool_calls` array on AiChatResponse so the
+ *     AiAssistantService orchestration loop stays provider-agnostic.
+ *
+ *   - `textCompletion()` — for the text generation popup on WYSIWYG editors.
+ *     Stateless single-shot prompt → text.
+ *
+ * Drivers are registered with the host via the module Registry (see
+ * App\Providers\DriverRegistryProvider for built-ins and
+ * InvoiceShelf\Modules\Registry::registerAiDriver() for module-contributed ones).
+ */
+abstract class AiDriver
+{
+    public function __construct(
+        protected string $apiKey,
+        protected array $config = [],
+    ) {}
+
+    /**
+     * Perform a chat completion.
+     *
+     * @param  array<int, array<string, mixed>>  $messages  OpenAI chat format: [['role' => 'user', 'content' => '...'], ...]
+     * @param  string  $model  Provider-specific model identifier, e.g. 'openai/gpt-4o'
+     * @param  array<int, array<string, mixed>>  $tools  OpenAI tools schema array (empty = no tool calling)
+     * @param  array<string, mixed>  $options  Provider-specific options (temperature, max_tokens, etc.)
+     *
+     * @throws AiException
+     */
+    abstract public function chatCompletion(
+        array $messages,
+        string $model,
+        array $tools = [],
+        array $options = [],
+    ): AiChatResponse;
+
+    /**
+     * Perform a single-shot text completion.
+     *
+     * Implementations may route this through chatCompletion() with a single
+     * user message — it's a convenience for callers that don't need history.
+     *
+     * @throws AiException
+     */
+    abstract public function textCompletion(
+        string $prompt,
+        string $model,
+        array $options = [],
+    ): string;
+
+    /**
+     * Validate that the configured API key and base URL can reach the provider.
+     *
+     * Called from admin "Test connection" buttons. Should make a cheap round-trip
+     * (list models, short completion, etc.) and throw AiException on failure.
+     *
+     * @return array<string, mixed> Provider info the UI can display (e.g. echoed model list)
+     *
+     * @throws AiException
+     */
+    abstract public function validateConnection(): array;
+
+    /**
+     * Optional: return the list of available model identifiers from the provider.
+     *
+     * Drivers that don't expose a models endpoint can leave this as an empty array.
+     * The UI falls back to the `suggested_models` declared in driver metadata.
+     *
+     * @return array<int, array{value: string, label: string}>
+     */
+    public function listModels(): array
+    {
+        return [];
+    }
+}