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/Http/Controllers/Admin/Settings/AiConfigurationController.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace App\Http\Controllers\Admin\Settings;
+
+use App\Http\Controllers\Controller;
+use App\Services\AiConfigurationService;
+use App\Support\Ai\AiDriverFactory;
+use App\Support\Ai\AiException;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
+
+class AiConfigurationController extends Controller
+{
+    public function __construct(
+        private readonly AiConfigurationService $aiConfigurationService,
+    ) {}
+
+    /**
+     * Get the global AI configuration with decrypted API key masked for response.
+     *
+     * @throws AuthorizationException
+     */
+    public function getConfig(): JsonResponse
+    {
+        $this->authorize('manage ai config');
+
+        $config = $this->aiConfigurationService->getGlobalConfig();
+
+        return response()->json($this->maskApiKey($config));
+    }
+
+    /**
+     * Persist the global AI configuration.
+     *
+     * If the submitted api_key is the masked placeholder, we retain the stored value —
+     * otherwise the user would have to re-enter the key every time they save the form.
+     *
+     * @throws AuthorizationException
+     * @throws ValidationException
+     */
+    public function saveConfig(Request $request): JsonResponse
+    {
+        $this->authorize('manage ai config');
+
+        $validated = $this->validate(
+            $request,
+            $this->aiConfigurationService->validationRules(allowDisabledCustomConfig: false),
+        );
+
+        // Preserve existing key when client submits the masked placeholder
+        if (($validated['ai_api_key'] ?? null) === '********' || ($validated['ai_api_key'] ?? null) === '') {
+            $existing = $this->aiConfigurationService->getGlobalConfig();
+            $validated['ai_api_key'] = $existing['ai_api_key'] ?? '';
+        }
+
+        $this->aiConfigurationService->saveGlobalConfig($validated);
+
+        return response()->json(['success' => 'ai_variables_save_successfully']);
+    }
+
+    /**
+     * Return the AI driver list for the admin UI — same shape as the exchange rate endpoint.
+     *
+     * @throws AuthorizationException
+     */
+    public function getDrivers(): JsonResponse
+    {
+        $this->authorize('manage ai config');
+
+        return response()->json([
+            'ai_drivers' => $this->aiConfigurationService->listDrivers(),
+        ]);
+    }
+
+    /**
+     * Test the currently configured AI provider by instantiating its driver and calling validateConnection().
+     *
+     * @throws AuthorizationException
+     */
+    public function testConnection(Request $request): JsonResponse
+    {
+        $this->authorize('manage ai config');
+
+        $this->validate($request, [
+            'ai_driver' => 'required|string',
+            'ai_api_key' => 'nullable|string',
+            'ai_base_url' => 'nullable|string|url',
+        ]);
+
+        // If the masked placeholder was submitted, fall back to the stored key
+        $apiKey = $request->input('ai_api_key');
+        if ($apiKey === '********' || $apiKey === null || $apiKey === '') {
+            $existing = $this->aiConfigurationService->getGlobalConfig();
+            $apiKey = $existing['ai_api_key'] ?? '';
+        }
+
+        if ($apiKey === '') {
+            return response()->json(['error' => 'missing_api_key'], 422);
+        }
+
+        try {
+            $driver = AiDriverFactory::make(
+                $request->input('ai_driver'),
+                $apiKey,
+                ['base_url' => $request->input('ai_base_url')],
+            );
+
+            $result = $driver->validateConnection();
+        } catch (AiException $e) {
+            return response()->json(['error' => $e->errorKey, 'message' => $e->getMessage()], 422);
+        }
+
+        return response()->json(['success' => true, 'details' => $result]);
+    }
+
+    /**
+     * Replace the stored API key with a masked placeholder so it's never returned to the client.
+     *
+     * @param  array<string, mixed>  $config
+     * @return array<string, mixed>
+     */
+    private function maskApiKey(array $config): array
+    {
+        if (! empty($config['ai_api_key'])) {
+            $config['ai_api_key'] = '********';
+        }
+
+        return $config;
+    }
+}

app/Http/Controllers/Company/General/BootstrapController.php

@@ -12,6 +12,7 @@ use App\Models\CompanySetting;
 use App\Models\Currency;
 use App\Models\Module;
 use App\Models\Setting;
+use App\Services\AiConfigurationService;
 use App\Traits\GeneratesMenuTrait;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -121,6 +122,8 @@ class BootstrapController extends Controller
 
         BouncerFacade::refreshFor($current_user);
 
+        $aiResolved = app(AiConfigurationService::class)->resolveForCompany($current_company->id);
+
         return response()->json([
             'current_user' => new UserResource($current_user),
             'current_user_settings' => $current_user_settings,
@@ -131,6 +134,11 @@ class BootstrapController extends Controller
             'current_company_currency' => $current_company_currency,
             'config' => config('invoiceshelf'),
             'global_settings' => $global_settings,
+            'ai' => [
+                'enabled' => $aiResolved !== null,
+                'chat_enabled' => (bool) ($aiResolved['chat_enabled'] ?? false),
+                'text_generation_enabled' => (bool) ($aiResolved['text_generation_enabled'] ?? false),
+            ],
             'main_menu' => $main_menu,
             'setting_menu' => $setting_menu,
             'modules' => Module::where('enabled', true)->pluck('name'),

app/Http/Controllers/Company/Settings/CompanyAiConfigurationController.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace App\Http\Controllers\Company\Settings;
+
+use App\Http\Controllers\Controller;
+use App\Services\AiConfigurationService;
+use App\Support\Ai\AiDriverFactory;
+use App\Support\Ai\AiException;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
+
+class CompanyAiConfigurationController extends Controller
+{
+    public function __construct(
+        private readonly AiConfigurationService $aiConfigurationService,
+    ) {}
+
+    /**
+     * Get the per-company AI config with decrypted API key masked for response.
+     */
+    public function getConfig(Request $request): JsonResponse
+    {
+        $config = $this->aiConfigurationService->getCompanyConfig($request->header('company'));
+
+        return response()->json($this->maskApiKey($config));
+    }
+
+    /**
+     * Persist the per-company AI config.
+     *
+     * Respects the `use_custom_ai_config` toggle — when OFF, only the toggle is written
+     * and the driver fields are discarded (same pattern as the mail company override).
+     *
+     * @throws ValidationException
+     */
+    public function saveConfig(Request $request): JsonResponse
+    {
+        $this->authorize('owner only');
+
+        $validated = $this->validate(
+            $request,
+            $this->aiConfigurationService->validationRules(allowDisabledCustomConfig: true),
+        );
+
+        // Preserve existing key when masked placeholder is submitted
+        if (($validated['ai_api_key'] ?? null) === '********' || ($validated['ai_api_key'] ?? null) === '') {
+            $existing = $this->aiConfigurationService->getCompanyConfig($request->header('company'));
+            $validated['ai_api_key'] = $existing['ai_api_key'] ?? '';
+        }
+
+        $this->aiConfigurationService->saveCompanyConfig(
+            $request->header('company'),
+            $validated,
+        );
+
+        return response()->json(['success' => true]);
+    }
+
+    /**
+     * Test a company-level AI configuration without persisting it.
+     *
+     * @throws ValidationException
+     */
+    public function testConnection(Request $request): JsonResponse
+    {
+        $this->authorize('owner only');
+
+        $this->validate($request, [
+            'ai_driver' => 'required|string',
+            'ai_api_key' => 'nullable|string',
+            'ai_base_url' => 'nullable|string|url',
+        ]);
+
+        $apiKey = $request->input('ai_api_key');
+        if ($apiKey === '********' || $apiKey === null || $apiKey === '') {
+            $existing = $this->aiConfigurationService->getCompanyConfig($request->header('company'));
+            $apiKey = $existing['ai_api_key'] ?? '';
+        }
+
+        if ($apiKey === '') {
+            return response()->json(['error' => 'missing_api_key'], 422);
+        }
+
+        try {
+            $driver = AiDriverFactory::make(
+                $request->input('ai_driver'),
+                $apiKey,
+                ['base_url' => $request->input('ai_base_url')],
+            );
+
+            $result = $driver->validateConnection();
+        } catch (AiException $e) {
+            return response()->json(['error' => $e->errorKey, 'message' => $e->getMessage()], 422);
+        }
+
+        return response()->json(['success' => true, 'details' => $result]);
+    }
+
+    /**
+     * @param  array<string, mixed>  $config
+     * @return array<string, mixed>
+     */
+    private function maskApiKey(array $config): array
+    {
+        if (! empty($config['ai_api_key'])) {
+            $config['ai_api_key'] = '********';
+        }
+
+        return $config;
+    }
+}

app/Http/Controllers/Setup/AiConfigurationController.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace App\Http\Controllers\Setup;
+
+use App\Http\Controllers\Controller;
+use App\Models\Setting;
+use App\Services\AiConfigurationService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Artisan;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Installer wizard step: optional "Enable AI" configuration.
+ *
+ * Runs without an authenticated user — the installer middleware allows public
+ * access until `profile_complete` is marked COMPLETED. Persists a minimal global
+ * AI config so the first super-admin doesn't have to revisit the admin panel
+ * just to turn on chat/text-generation after install.
+ *
+ * Skipping the step (posting ai_enabled=NO) is the default path — users can
+ * always configure AI later from Admin → Settings → AI Configuration.
+ */
+class AiConfigurationController extends Controller
+{
+    public function __construct(
+        private readonly AiConfigurationService $aiConfigurationService,
+    ) {}
+
+    /**
+     * Return the current AI config defaults plus the driver list for the wizard form.
+     */
+    public function show(): JsonResponse
+    {
+        return response()->json([
+            'config' => $this->aiConfigurationService->getGlobalConfig(),
+            'drivers' => $this->aiConfigurationService->listDrivers(),
+        ]);
+    }
+
+    /**
+     * Persist the installer's AI config choice and advance the wizard step.
+     *
+     * @throws ValidationException
+     */
+    public function save(Request $request): JsonResponse
+    {
+        Artisan::call('optimize:clear');
+
+        $validated = $this->validate($request, [
+            'ai_enabled' => 'required|in:YES,NO',
+            'ai_driver' => 'required_if:ai_enabled,YES|nullable|string',
+            'ai_api_key' => 'required_if:ai_enabled,YES|nullable|string',
+            'ai_base_url' => 'nullable|string|url',
+            'ai_chat_enabled' => 'nullable|in:YES,NO',
+            'ai_chat_model' => 'nullable|string|max:200',
+            'ai_text_generation_enabled' => 'nullable|in:YES,NO',
+            'ai_text_generation_model' => 'nullable|string|max:200',
+        ]);
+
+        $this->aiConfigurationService->saveGlobalConfig($validated);
+
+        // Advance the installer's profile_complete marker if we're the first to touch it.
+        // Mail uses `4`; we'll use the next sentinel but leave actual completion to the
+        // final Preferences step (which sets 'COMPLETED'). The sentinel value is ignored
+        // once COMPLETED is written — it only matters for step-tracking during install.
+        $profileComplete = Setting::getSetting('profile_complete');
+        if ($profileComplete !== 'COMPLETED' && (int) $profileComplete < 5) {
+            Setting::setSetting('profile_complete', 5);
+        }
+
+        return response()->json(['success' => true]);
+    }
+}