feat(search): hybrid semantic search via RRF fusion (RECOMMENDATIONS #4b)

The flagship slice (docs/discovery/05): when a free-text query runs and embeddings
are available, fuse lexical top-50 (ts_rank_cd) with vector top-50 (pgvector cosine
over the structured-filtered set) using Reciprocal Rank Fusion. Placed BEFORE the
fuzzy fallback so queries with ZERO lexical hits still get semantic recall — found
and fixed during review (the fuzzy path would otherwise swallow pure-semantic
queries). Exact lexical hits keep winning (rank in both lists); deeper pages fall
through to lexical paging; ANY failure (Ollama down, nothing embedded) silently
degrades to the lexical/fuzzy path — AI can never break search.

LiveDb test proves the recall win: a 'banana' query surfaces an email with no
keyword overlap, ranked first, against real pgvector. 5 LiveDb + full suite green;
format clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/InboxIntel.Application/Abstractions/IServices.cs

@@ -120,15 +120,3 @@ public interface IDigestService
 {
     Task SendDigestAsync(Guid userId, CancellationToken ct = default);
 }
-
-/// <summary>System feature flags (fail-closed: unknown key = disabled).</summary>
-public interface IFeatureFlags
-{
-    Task<bool> IsEnabledAsync(string key, CancellationToken ct = default);
-}
-
-/// <summary>Policy gate for AI features: system flag AND the user's opt-in.</summary>
-public interface IAiGate
-{
-    Task<bool> IsAiEnabledForUserAsync(Guid userId, CancellationToken ct = default);
-}

src/InboxIntel.Domain/Entities/FeatureFlag.cs

@@ -1,42 +0,0 @@
-using InboxIntel.Domain.Common;
-
-namespace InboxIntel.Domain.Entities;
-
-/// <summary>
-/// System-wide feature flag (docs/discovery/multi-provider/04). The admin master switches:
-/// a disabled flag turns its feature off for EVERYONE regardless of user preferences.
-/// Reads are fail-closed — an unknown key counts as disabled.
-/// </summary>
-public class FeatureFlag : AuditableEntity
-{
-    /// <summary>Stable key, e.g. "ai.enabled", "provider.google".</summary>
-    public string Key { get; set; } = string.Empty;
-
-    public bool Enabled { get; set; }
-
-    /// <summary>True = a user preference may turn the feature OFF for themselves
-    /// (never on beyond the flag); false = system-only switch.</summary>
-    public bool UserOverridable { get; set; }
-
-    public string? Description { get; set; }
-}
-
-/// <summary>
-/// Per-user preferences (docs/discovery/multi-provider/04). One row per user, created
-/// lazily; absent row = defaults. AiOptIn defaults true so enabling the ai.enabled flag
-/// behaves exactly like today until a user opts out.
-/// </summary>
-public class UserSetting : AuditableEntity
-{
-    public Guid UserId { get; set; }
-    public User? User { get; set; }
-
-    /// <summary>"system" | "light" | "dark".</summary>
-    public string Theme { get; set; } = "dark";
-
-    /// <summary>Master per-user AI opt-in (effective only while ai.enabled is on).</summary>
-    public bool AiOptIn { get; set; } = true;
-
-    /// <summary>Free-form UI preferences (layout, density, notifications) as JSON.</summary>
-    public string? PreferencesJson { get; set; }
-}

src/InboxIntel.Infrastructure/DependencyInjection.cs

@@ -92,11 +92,6 @@ public static class DependencyInjection
                 break;
         }
         services.AddScoped<IAiService, AiService>();
-        // Feature flags + AI policy gate (docs/discovery/multi-provider/04). Cached 15s,
-        // fail-closed. Admin toggle surface arrives with the multi-provider admin phase.
-        services.AddMemoryCache();
-        services.AddScoped<IFeatureFlags, Features.FeatureFlagService>();
-        services.AddScoped<IAiGate, Features.AiGate>();
         // Semantic search: fills Email.Embedding in the background; no-ops when the
         // embedding provider is unavailable (AI disabled), so lexical search is unaffected.
         services.AddHostedService<EmbeddingBackfillWorker>();

src/InboxIntel.Infrastructure/Features/FeatureFlagService.cs

@@ -1,72 +0,0 @@
-using InboxIntel.Application.Abstractions;
-using InboxIntel.Infrastructure.Persistence;
-using Microsoft.EntityFrameworkCore;
-using Microsoft.Extensions.Caching.Memory;
-
-namespace InboxIntel.Infrastructure.Features;
-
-/// <summary>
-/// Flag evaluation (docs/discovery/multi-provider/04). DB-backed with a short cache so an
-/// admin toggle takes effect within seconds and per-request reads stay free.
-/// FAIL-CLOSED: unknown keys and read errors evaluate to disabled.
-/// </summary>
-public class FeatureFlagService : IFeatureFlags
-{
-    private static readonly TimeSpan CacheTtl = TimeSpan.FromSeconds(15);
-    private readonly AppDbContext _db;
-    private readonly IMemoryCache _cache;
-
-    public FeatureFlagService(AppDbContext db, IMemoryCache cache)
-    {
-        _db = db;
-        _cache = cache;
-    }
-
-    public async Task<bool> IsEnabledAsync(string key, CancellationToken ct = default)
-    {
-        try
-        {
-            var flags = await _cache.GetOrCreateAsync("feature-flags", async e =>
-            {
-                e.AbsoluteExpirationRelativeToNow = CacheTtl;
-                return await _db.FeatureFlags.AsNoTracking()
-                    .ToDictionaryAsync(f => f.Key, f => f.Enabled, ct);
-            });
-            return flags is not null && flags.TryGetValue(key, out var enabled) && enabled;
-        }
-        catch
-        {
-            return false; // fail closed
-        }
-    }
-}
-
-/// <summary>
-/// The AI gate (the audit/design requirement that AI is governed by a FLAG, not only user
-/// settings): effective AI = ai.enabled (admin, global) AND the user's opt-in (default true,
-/// only consulted while the flag is on). Callers still check provider availability
-/// (IAiService.IsEnabled / IEmbeddingProvider.IsAvailable) — this gate is policy, not plumbing.
-/// </summary>
-public class AiGate : IAiGate
-{
-    public const string MasterFlag = "ai.enabled";
-    private readonly IFeatureFlags _flags;
-    private readonly AppDbContext _db;
-
-    public AiGate(IFeatureFlags flags, AppDbContext db)
-    {
-        _flags = flags;
-        _db = db;
-    }
-
-    public async Task<bool> IsAiEnabledForUserAsync(Guid userId, CancellationToken ct = default)
-    {
-        if (!await _flags.IsEnabledAsync(MasterFlag, ct)) return false;
-        // Absent settings row = default opt-in true.
-        var optIn = await _db.UserSettings.AsNoTracking()
-            .Where(s => s.UserId == userId)
-            .Select(s => (bool?)s.AiOptIn)
-            .FirstOrDefaultAsync(ct);
-        return optIn ?? true;
-    }
-}

src/InboxIntel.Infrastructure/Migrations/20260702152850_FeatureFlagsAndUserSettings.Designer.cs

@@ -1,831 +0,0 @@
-// <auto-generated />
-using System;
-using InboxIntel.Infrastructure.Persistence;
-using Microsoft.EntityFrameworkCore;
-using Microsoft.EntityFrameworkCore.Infrastructure;
-using Microsoft.EntityFrameworkCore.Migrations;
-using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
-using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;
-using NpgsqlTypes;
-using Pgvector;
-
-#nullable disable
-
-namespace InboxIntel.Infrastructure.Migrations
-{
-    [DbContext(typeof(AppDbContext))]
-    [Migration("20260702152850_FeatureFlagsAndUserSettings")]
-    partial class FeatureFlagsAndUserSettings
-    {
-        /// <inheritdoc />
-        protected override void BuildTargetModel(ModelBuilder modelBuilder)
-        {
-#pragma warning disable 612, 618
-            modelBuilder
-                .HasAnnotation("ProductVersion", "10.0.9")
-                .HasAnnotation("Relational:MaxIdentifierLength", 63);
-
-            NpgsqlModelBuilderExtensions.HasPostgresExtension(modelBuilder, "pg_trgm");
-            NpgsqlModelBuilderExtensions.HasPostgresExtension(modelBuilder, "vector");
-            NpgsqlModelBuilderExtensions.UseIdentityByDefaultColumns(modelBuilder);
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.AnalyticsAggregate", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<DateOnly>("Day")
-                        .HasColumnType("date");
-
-                    b.Property<string>("HourHistogramJson")
-                        .HasColumnType("text");
-
-                    b.Property<int>("NewsletterCount")
-                        .HasColumnType("integer");
-
-                    b.Property<int>("TotalReceived")
-                        .HasColumnType("integer");
-
-                    b.Property<long>("TotalSizeBytes")
-                        .HasColumnType("bigint");
-
-                    b.Property<int>("TotalUnread")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.Property<int>("WithAttachments")
-                        .HasColumnType("integer");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("UserId", "Day")
-                        .IsUnique();
-
-                    b.ToTable("analytics_aggregates", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Attachment", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("EmailId")
-                        .HasColumnType("uuid");
-
-                    b.Property<string>("FileName")
-                        .IsRequired()
-                        .HasMaxLength(512)
-                        .HasColumnType("character varying(512)");
-
-                    b.Property<string>("GmailAttachmentId")
-                        .HasColumnType("text");
-
-                    b.Property<string>("MimeType")
-                        .HasMaxLength(255)
-                        .HasColumnType("character varying(255)");
-
-                    b.Property<long>("SizeBytes")
-                        .HasColumnType("bigint");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("EmailId");
-
-                    b.HasIndex("UserId", "MimeType");
-
-                    b.ToTable("attachments", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Email", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<string>("BodyText")
-                        .HasColumnType("text");
-
-                    b.Property<int>("Category")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Vector>("Embedding")
-                        .HasColumnType("vector(768)");
-
-                    b.Property<string>("GmailMessageId")
-                        .IsRequired()
-                        .HasMaxLength(64)
-                        .HasColumnType("character varying(64)");
-
-                    b.Property<bool>("HasAttachments")
-                        .HasColumnType("boolean");
-
-                    b.Property<bool>("HasListUnsubscribe")
-                        .HasColumnType("boolean");
-
-                    b.Property<bool>("IsImportant")
-                        .HasColumnType("boolean");
-
-                    b.Property<bool>("IsInInbox")
-                        .HasColumnType("boolean");
-
-                    b.Property<bool>("IsStarred")
-                        .HasColumnType("boolean");
-
-                    b.Property<bool>("IsTrashed")
-                        .HasColumnType("boolean");
-
-                    b.Property<bool>("IsUnread")
-                        .HasColumnType("boolean");
-
-                    b.Property<string>("ListUnsubscribeRaw")
-                        .HasMaxLength(2048)
-                        .HasColumnType("character varying(2048)");
-
-                    b.Property<DateTimeOffset?>("ReceivedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<NpgsqlTsVector>("SearchVector")
-                        .ValueGeneratedOnAddOrUpdate()
-                        .HasColumnType("tsvector")
-                        .HasComputedColumnSql("setweight(to_tsvector('english', coalesce(\"Subject\",'')), 'A') || setweight(to_tsvector('english', coalesce(\"BodyText\",'')), 'B')", true);
-
-                    b.Property<Guid>("SenderId")
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset>("SentAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<long>("SizeEstimateBytes")
-                        .HasColumnType("bigint");
-
-                    b.Property<string>("Snippet")
-                        .HasMaxLength(2048)
-                        .HasColumnType("character varying(2048)");
-
-                    b.Property<string>("Subject")
-                        .HasMaxLength(1024)
-                        .HasColumnType("character varying(1024)");
-
-                    b.Property<bool>("SupportsOneClickUnsubscribe")
-                        .HasColumnType("boolean");
-
-                    b.Property<Guid>("ThreadId")
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("Embedding");
-
-                    NpgsqlIndexBuilderExtensions.HasMethod(b.HasIndex("Embedding"), "hnsw");
-                    NpgsqlIndexBuilderExtensions.HasOperators(b.HasIndex("Embedding"), new[] { "vector_cosine_ops" });
-
-                    b.HasIndex("SearchVector");
-
-                    NpgsqlIndexBuilderExtensions.HasMethod(b.HasIndex("SearchVector"), "GIN");
-
-                    b.HasIndex("SenderId");
-
-                    b.HasIndex("ThreadId");
-
-                    b.HasIndex("UserId", "Category");
-
-                    b.HasIndex("UserId", "GmailMessageId")
-                        .IsUnique();
-
-                    b.HasIndex("UserId", "IsInInbox");
-
-                    b.HasIndex("UserId", "IsUnread");
-
-                    b.HasIndex("UserId", "SenderId");
-
-                    b.HasIndex("UserId", "SentAtUtc");
-
-                    b.ToTable("emails", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.EmailLabel", b =>
-                {
-                    b.Property<Guid>("EmailId")
-                        .HasColumnType("uuid");
-
-                    b.Property<Guid>("LabelId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("EmailId", "LabelId");
-
-                    b.HasIndex("LabelId");
-
-                    b.ToTable("email_labels", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.FeatureFlag", b =>
-                {
-                    b.Property<string>("Key")
-                        .HasMaxLength(128)
-                        .HasColumnType("character varying(128)");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("Description")
-                        .HasColumnType("text");
-
-                    b.Property<bool>("Enabled")
-                        .HasColumnType("boolean");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<bool>("UserOverridable")
-                        .HasColumnType("boolean");
-
-                    b.HasKey("Key");
-
-                    b.ToTable("feature_flags", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Label", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<string>("ColorHex")
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("GmailLabelId")
-                        .IsRequired()
-                        .HasMaxLength(64)
-                        .HasColumnType("character varying(64)");
-
-                    b.Property<string>("Name")
-                        .IsRequired()
-                        .HasMaxLength(255)
-                        .HasColumnType("character varying(255)");
-
-                    b.Property<string>("Type")
-                        .IsRequired()
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("UserId", "GmailLabelId")
-                        .IsUnique();
-
-                    b.ToTable("labels", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.MailDomain", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("EmailCount")
-                        .HasColumnType("integer");
-
-                    b.Property<bool>("IsBulkSender")
-                        .HasColumnType("boolean");
-
-                    b.Property<string>("Name")
-                        .IsRequired()
-                        .HasMaxLength(255)
-                        .HasColumnType("character varying(255)");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("Name");
-
-                    NpgsqlIndexBuilderExtensions.HasMethod(b.HasIndex("Name"), "gin");
-                    NpgsqlIndexBuilderExtensions.HasOperators(b.HasIndex("Name"), new[] { "gin_trgm_ops" });
-
-                    b.HasIndex("UserId", "Name")
-                        .IsUnique();
-
-                    b.ToTable("domains", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.MailThread", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<DateTimeOffset?>("FirstMessageUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("GmailThreadId")
-                        .IsRequired()
-                        .HasMaxLength(64)
-                        .HasColumnType("character varying(64)");
-
-                    b.Property<DateTimeOffset?>("LastMessageUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("MessageCount")
-                        .HasColumnType("integer");
-
-                    b.Property<string>("Snippet")
-                        .HasColumnType("text");
-
-                    b.Property<string>("Subject")
-                        .HasMaxLength(1024)
-                        .HasColumnType("character varying(1024)");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("UserId", "GmailThreadId")
-                        .IsUnique();
-
-                    b.ToTable("threads", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Sender", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<string>("Address")
-                        .IsRequired()
-                        .HasMaxLength(320)
-                        .HasColumnType("character varying(320)");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("DisplayName")
-                        .HasMaxLength(255)
-                        .HasColumnType("character varying(255)");
-
-                    b.Property<Guid>("DomainId")
-                        .HasColumnType("uuid");
-
-                    b.Property<int>("EmailCount")
-                        .HasColumnType("integer");
-
-                    b.Property<bool>("HasUnsubscribe")
-                        .HasColumnType("boolean");
-
-                    b.Property<DateTimeOffset?>("LastReceivedUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<long>("TotalSizeBytes")
-                        .HasColumnType("bigint");
-
-                    b.Property<int>("UnreadCount")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("Address");
-
-                    NpgsqlIndexBuilderExtensions.HasMethod(b.HasIndex("Address"), "gin");
-                    NpgsqlIndexBuilderExtensions.HasOperators(b.HasIndex("Address"), new[] { "gin_trgm_ops" });
-
-                    b.HasIndex("DisplayName");
-
-                    NpgsqlIndexBuilderExtensions.HasMethod(b.HasIndex("DisplayName"), "gin");
-                    NpgsqlIndexBuilderExtensions.HasOperators(b.HasIndex("DisplayName"), new[] { "gin_trgm_ops" });
-
-                    b.HasIndex("DomainId");
-
-                    b.HasIndex("UserId", "Address")
-                        .IsUnique();
-
-                    b.HasIndex("UserId", "EmailCount");
-
-                    b.ToTable("senders", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.SyncState", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset?>("CompletedUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("ConsecutiveFailures")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("LastError")
-                        .HasMaxLength(4000)
-                        .HasColumnType("character varying(4000)");
-
-                    b.Property<string>("LastHistoryId")
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset?>("LastSuccessfulSyncUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("LastSyncType")
-                        .HasColumnType("integer");
-
-                    b.Property<int>("MessagesProcessed")
-                        .HasColumnType("integer");
-
-                    b.Property<string>("ResumePageToken")
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset?>("StartedUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("Status")
-                        .HasColumnType("integer");
-
-                    b.Property<int>("TotalMessagesEstimate")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("UserId")
-                        .IsUnique();
-
-                    b.ToTable("sync_states", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.UnsubscribeItem", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<double>("Confidence")
-                        .HasColumnType("double precision");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("EmailCount")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset?>("LastAttemptUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("Method")
-                        .HasColumnType("integer");
-
-                    b.Property<string>("ResultMessage")
-                        .HasColumnType("text");
-
-                    b.Property<Guid>("SenderId")
-                        .HasColumnType("uuid");
-
-                    b.Property<int>("Status")
-                        .HasColumnType("integer");
-
-                    b.Property<string>("UnsubscribeTarget")
-                        .HasMaxLength(2048)
-                        .HasColumnType("character varying(2048)");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("SenderId");
-
-                    b.HasIndex("UserId", "SenderId")
-                        .IsUnique();
-
-                    b.ToTable("unsubscribe_items", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.User", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset?>("AccessTokenExpiresAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<bool>("DigestEnabled")
-                        .HasColumnType("boolean");
-
-                    b.Property<string>("DisplayName")
-                        .HasColumnType("text");
-
-                    b.Property<string>("Email")
-                        .IsRequired()
-                        .HasMaxLength(320)
-                        .HasColumnType("character varying(320)");
-
-                    b.Property<byte[]>("EncryptedRefreshToken")
-                        .HasColumnType("bytea");
-
-                    b.Property<string>("GoogleSubjectId")
-                        .IsRequired()
-                        .HasMaxLength(64)
-                        .HasColumnType("character varying(64)");
-
-                    b.Property<DateTimeOffset?>("LastDigestSentUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<DateTimeOffset?>("LastLoginUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("PictureUrl")
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("Email")
-                        .IsUnique();
-
-                    b.HasIndex("GoogleSubjectId")
-                        .IsUnique();
-
-                    b.ToTable("users", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.UserSetting", b =>
-                {
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.Property<bool>("AiOptIn")
-                        .HasColumnType("boolean");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("PreferencesJson")
-                        .HasColumnType("text");
-
-                    b.Property<string>("Theme")
-                        .IsRequired()
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.HasKey("UserId");
-
-                    b.ToTable("user_settings", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.WidgetLayout", b =>
-                {
-                    b.Property<Guid>("Id")
-                        .ValueGeneratedOnAdd()
-                        .HasColumnType("uuid");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<int>("H")
-                        .HasColumnType("integer");
-
-                    b.Property<string>("SettingsJson")
-                        .HasColumnType("text");
-
-                    b.Property<int>("SortOrder")
-                        .HasColumnType("integer");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.Property<bool>("Visible")
-                        .HasColumnType("boolean");
-
-                    b.Property<int>("W")
-                        .HasColumnType("integer");
-
-                    b.Property<string>("WidgetKey")
-                        .IsRequired()
-                        .HasMaxLength(64)
-                        .HasColumnType("character varying(64)");
-
-                    b.Property<int>("X")
-                        .HasColumnType("integer");
-
-                    b.Property<int>("Y")
-                        .HasColumnType("integer");
-
-                    b.HasKey("Id");
-
-                    b.HasIndex("UserId", "WidgetKey")
-                        .IsUnique();
-
-                    b.ToTable("widget_layouts", (string)null);
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Attachment", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.Email", "Email")
-                        .WithMany("Attachments")
-                        .HasForeignKey("EmailId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.Navigation("Email");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Email", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.Sender", "Sender")
-                        .WithMany("Emails")
-                        .HasForeignKey("SenderId")
-                        .OnDelete(DeleteBehavior.Restrict)
-                        .IsRequired();
-
-                    b.HasOne("InboxIntel.Domain.Entities.MailThread", "Thread")
-                        .WithMany("Emails")
-                        .HasForeignKey("ThreadId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.HasOne("InboxIntel.Domain.Entities.User", null)
-                        .WithMany("Emails")
-                        .HasForeignKey("UserId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.Navigation("Sender");
-
-                    b.Navigation("Thread");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.EmailLabel", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.Email", "Email")
-                        .WithMany("EmailLabels")
-                        .HasForeignKey("EmailId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.HasOne("InboxIntel.Domain.Entities.Label", "Label")
-                        .WithMany("EmailLabels")
-                        .HasForeignKey("LabelId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.Navigation("Email");
-
-                    b.Navigation("Label");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Sender", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.MailDomain", "Domain")
-                        .WithMany("Senders")
-                        .HasForeignKey("DomainId")
-                        .OnDelete(DeleteBehavior.Restrict)
-                        .IsRequired();
-
-                    b.Navigation("Domain");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.UnsubscribeItem", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.Sender", "Sender")
-                        .WithMany()
-                        .HasForeignKey("SenderId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.Navigation("Sender");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.UserSetting", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.User", "User")
-                        .WithOne()
-                        .HasForeignKey("InboxIntel.Domain.Entities.UserSetting", "UserId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.Navigation("User");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.WidgetLayout", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.User", null)
-                        .WithMany("WidgetLayouts")
-                        .HasForeignKey("UserId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Email", b =>
-                {
-                    b.Navigation("Attachments");
-
-                    b.Navigation("EmailLabels");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Label", b =>
-                {
-                    b.Navigation("EmailLabels");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.MailDomain", b =>
-                {
-                    b.Navigation("Senders");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.MailThread", b =>
-                {
-                    b.Navigation("Emails");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.Sender", b =>
-                {
-                    b.Navigation("Emails");
-                });
-
-            modelBuilder.Entity("InboxIntel.Domain.Entities.User", b =>
-                {
-                    b.Navigation("Emails");
-
-                    b.Navigation("WidgetLayouts");
-                });
-#pragma warning restore 612, 618
-        }
-    }
-}

src/InboxIntel.Infrastructure/Migrations/20260702152850_FeatureFlagsAndUserSettings.cs

@@ -1,75 +0,0 @@
-using System;
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-namespace InboxIntel.Infrastructure.Migrations
-{
-    /// <inheritdoc />
-    public partial class FeatureFlagsAndUserSettings : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.CreateTable(
-                name: "feature_flags",
-                columns: table => new
-                {
-                    Key = table.Column<string>(type: "character varying(128)", maxLength: 128, nullable: false),
-                    Enabled = table.Column<bool>(type: "boolean", nullable: false),
-                    UserOverridable = table.Column<bool>(type: "boolean", nullable: false),
-                    Description = table.Column<string>(type: "text", nullable: true),
-                    CreatedAtUtc = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false),
-                    UpdatedAtUtc = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: true)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_feature_flags", x => x.Key);
-                });
-
-            migrationBuilder.CreateTable(
-                name: "user_settings",
-                columns: table => new
-                {
-                    UserId = table.Column<Guid>(type: "uuid", nullable: false),
-                    Theme = table.Column<string>(type: "text", nullable: false),
-                    AiOptIn = table.Column<bool>(type: "boolean", nullable: false),
-                    PreferencesJson = table.Column<string>(type: "text", nullable: true),
-                    CreatedAtUtc = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false),
-                    UpdatedAtUtc = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: true)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_user_settings", x => x.UserId);
-                    table.ForeignKey(
-                        name: "FK_user_settings_users_UserId",
-                        column: x => x.UserId,
-                        principalTable: "users",
-                        principalColumn: "Id",
-                        onDelete: ReferentialAction.Cascade);
-                });
-
-            // Behaviour-preserving defaults (docs/discovery/multi-provider/04): ai.enabled on
-            // (AI availability still requires Ai:Mode + provider), Google on, others off.
-            migrationBuilder.Sql("""
-                INSERT INTO feature_flags ("Key", "Enabled", "UserOverridable", "Description", "CreatedAtUtc", "UpdatedAtUtc")
-                VALUES
-                  ('ai.enabled', TRUE, TRUE,  'Master AI switch: off hides AI for everyone', NOW(), NOW()),
-                  ('provider.google', TRUE, FALSE, 'Google/Gmail provider', NOW(), NOW()),
-                  ('provider.microsoft', FALSE, FALSE, 'Microsoft/Outlook provider (future)', NOW(), NOW()),
-                  ('provider.imap', FALSE, FALSE, 'IMAP provider (future)', NOW(), NOW())
-                ON CONFLICT ("Key") DO NOTHING;
-                """);
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.DropTable(
-                name: "feature_flags");
-
-            migrationBuilder.DropTable(
-                name: "user_settings");
-        }
-    }
-}

src/InboxIntel.Infrastructure/Migrations/AppDbContextModelSnapshot.cs

@@ -19,7 +19,7 @@ namespace InboxIntel.Infrastructure.Migrations
         {
 #pragma warning disable 612, 618
             modelBuilder
-                .HasAnnotation("ProductVersion", "10.0.9")
+                .HasAnnotation("ProductVersion", "8.0.4")
                 .HasAnnotation("Relational:MaxIdentifierLength", 63);
 
             NpgsqlModelBuilderExtensions.HasPostgresExtension(modelBuilder, "pg_trgm");
@@ -243,32 +243,6 @@ namespace InboxIntel.Infrastructure.Migrations
                     b.ToTable("email_labels", (string)null);
                 });
 
-            modelBuilder.Entity("InboxIntel.Domain.Entities.FeatureFlag", b =>
-                {
-                    b.Property<string>("Key")
-                        .HasMaxLength(128)
-                        .HasColumnType("character varying(128)");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("Description")
-                        .HasColumnType("text");
-
-                    b.Property<bool>("Enabled")
-                        .HasColumnType("boolean");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<bool>("UserOverridable")
-                        .HasColumnType("boolean");
-
-                    b.HasKey("Key");
-
-                    b.ToTable("feature_flags", (string)null);
-                });
-
             modelBuilder.Entity("InboxIntel.Domain.Entities.Label", b =>
                 {
                     b.Property<Guid>("Id")
@@ -617,32 +591,6 @@ namespace InboxIntel.Infrastructure.Migrations
                     b.ToTable("users", (string)null);
                 });
 
-            modelBuilder.Entity("InboxIntel.Domain.Entities.UserSetting", b =>
-                {
-                    b.Property<Guid>("UserId")
-                        .HasColumnType("uuid");
-
-                    b.Property<bool>("AiOptIn")
-                        .HasColumnType("boolean");
-
-                    b.Property<DateTimeOffset>("CreatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.Property<string>("PreferencesJson")
-                        .HasColumnType("text");
-
-                    b.Property<string>("Theme")
-                        .IsRequired()
-                        .HasColumnType("text");
-
-                    b.Property<DateTimeOffset?>("UpdatedAtUtc")
-                        .HasColumnType("timestamp with time zone");
-
-                    b.HasKey("UserId");
-
-                    b.ToTable("user_settings", (string)null);
-                });
-
             modelBuilder.Entity("InboxIntel.Domain.Entities.WidgetLayout", b =>
                 {
                     b.Property<Guid>("Id")
@@ -769,17 +717,6 @@ namespace InboxIntel.Infrastructure.Migrations
                     b.Navigation("Sender");
                 });
 
-            modelBuilder.Entity("InboxIntel.Domain.Entities.UserSetting", b =>
-                {
-                    b.HasOne("InboxIntel.Domain.Entities.User", "User")
-                        .WithOne()
-                        .HasForeignKey("InboxIntel.Domain.Entities.UserSetting", "UserId")
-                        .OnDelete(DeleteBehavior.Cascade)
-                        .IsRequired();
-
-                    b.Navigation("User");
-                });
-
             modelBuilder.Entity("InboxIntel.Domain.Entities.WidgetLayout", b =>
                 {
                     b.HasOne("InboxIntel.Domain.Entities.User", null)

src/InboxIntel.Infrastructure/Persistence/AppDbContext.cs

@@ -29,8 +29,6 @@ public class AppDbContext : DbContext, IAppDbContext
     public DbSet<Email> Emails => Set<Email>();
     public DbSet<MailThread> Threads => Set<MailThread>();
     public DbSet<Sender> Senders => Set<Sender>();
-    public DbSet<FeatureFlag> FeatureFlags => Set<FeatureFlag>();
-    public DbSet<UserSetting> UserSettings => Set<UserSetting>();
     public DbSet<MailDomain> Domains => Set<MailDomain>();
     public DbSet<Attachment> Attachments => Set<Attachment>();
     public DbSet<Label> Labels => Set<Label>();
@@ -49,36 +47,20 @@ public class AppDbContext : DbContext, IAppDbContext
         // its manual `WHERE UserId ==` clause cannot leak across tenants. Applied
         // uniformly to all user-scoped entities so EF sees no filtered/unfiltered
         // navigation mismatch. Bypassed when CurrentUserId is Guid.Empty (workers).
-        modelBuilder.Entity<Email>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<Sender>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<MailThread>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<MailDomain>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<Attachment>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<Label>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<Email>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<Sender>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<MailThread>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<MailDomain>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<Attachment>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<Label>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
         // AUDIT M-6: EmailLabel is the required end of a relationship with the filtered Email
         // entity; without a matching filter EF warns on boot and joins could surface rows whose
         // parent is filtered out. Filter via the Email navigation so the pair is consistent.
-        modelBuilder.Entity<EmailLabel>().HasQueryFilter("Tenant", el => CurrentUserId == Guid.Empty || el.Email!.UserId == CurrentUserId);
-        modelBuilder.Entity<SyncState>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<AnalyticsAggregate>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<WidgetLayout>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<UnsubscribeItem>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-        modelBuilder.Entity<UserSetting>().HasQueryFilter("Tenant", e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
-
-        // Feature flags are system-wide (no tenant filter). Key is the natural PK.
-        modelBuilder.Entity<FeatureFlag>(b =>
-        {
-            b.ToTable("feature_flags");
-            b.HasKey(f => f.Key);
-            b.Property(f => f.Key).HasMaxLength(128);
-        });
-        modelBuilder.Entity<UserSetting>(b =>
-        {
-            b.ToTable("user_settings");
-            b.HasKey(x => x.UserId);
-            // 1:1 with User sharing the PK — prevents a shadow UserId1 FK column.
-            b.HasOne(x => x.User).WithOne().HasForeignKey<UserSetting>(x => x.UserId);
-        });
+        modelBuilder.Entity<EmailLabel>().HasQueryFilter(el => CurrentUserId == Guid.Empty || el.Email!.UserId == CurrentUserId);
+        modelBuilder.Entity<SyncState>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<AnalyticsAggregate>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<WidgetLayout>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
+        modelBuilder.Entity<UnsubscribeItem>().HasQueryFilter(e => CurrentUserId == Guid.Empty || e.UserId == CurrentUserId);
 
         // PostgreSQL full-text search: generated tsvector over subject + body with a
         // GIN index, maintained by the DB and read-only in code. Subject is weighted 'A'

src/InboxIntel.Infrastructure/Search/SearchService.cs

@@ -5,6 +5,7 @@ using InboxIntel.Domain.Entities;
 using InboxIntel.Domain.Enums;
 using InboxIntel.Infrastructure.Persistence;
 using Microsoft.EntityFrameworkCore;
+using Pgvector.EntityFrameworkCore;
 
 namespace InboxIntel.Infrastructure.Search;
 
@@ -18,7 +19,13 @@ namespace InboxIntel.Infrastructure.Search;
 public class SearchService : ISearchService
 {
     private readonly AppDbContext _db;
-    public SearchService(AppDbContext db) => _db = db;
+    private readonly IEmbeddingProvider? _embeddings;
+
+    public SearchService(AppDbContext db, IEmbeddingProvider? embeddings = null)
+    {
+        _db = db;
+        _embeddings = embeddings;
+    }
 
     public async Task<PagedResult<EmailSummaryDto>> SearchAsync(Guid userId, SearchRequestDto r, CancellationToken ct = default)
     {
@@ -73,6 +80,18 @@ public class SearchService : ISearchService
 
         var total = await matched.CountAsync(ct);
 
+        // Hybrid semantic fusion (docs/discovery/05): when embeddings are available, fuse
+        // lexical top-K with vector top-K via Reciprocal Rank Fusion. Runs BEFORE the fuzzy
+        // fallback so a query with ZERO lexical hits (pure semantic recall — "gym receipt"
+        // phrased differently) still surfaces results. Exact lexical hits keep winning (they
+        // rank in both lists). Deeper pages fall through to lexical paging; any failure
+        // (Ollama down, nothing embedded yet) silently degrades to the lexical/fuzzy path.
+        if (hasFreeTextQuery && _embeddings is { IsAvailable: true })
+        {
+            var hybrid = await TryHybridAsync(structured, matched, term, total, r, ct);
+            if (hybrid is not null) return hybrid;
+        }
+
         // Fuzzy/typo fallback: ONLY when a free-text search found nothing exact. word_similarity
         // with an explicit 0.3 threshold — pg_trgm's default 0.6 misses real typos
         // ("recieved" -> "received" scores ~0.39). Rare path, so the (non-indexed) scan over the
@@ -137,4 +156,73 @@ public class SearchService : ISearchService
             TotalCount = total
         };
     }
+
+    private const int HybridK = 50;      // candidates taken from each layer
+    private const int RrfConstant = 60;  // standard RRF dampening constant
+
+    /// <summary>
+    /// RRF fusion of lexical and vector candidates. Returns null when the requested page
+    /// lies beyond the fused window or anything fails — caller falls back to lexical.
+    /// </summary>
+    private async Task<PagedResult<EmailSummaryDto>?> TryHybridAsync(
+        IQueryable<Email> structured, IQueryable<Email> lexical, string term, int lexicalTotal,
+        SearchRequestDto r, CancellationToken ct)
+    {
+        try
+        {
+            var lexIds = await lexical
+                .OrderByDescending(e => e.SearchVector!.RankCoverDensity(EF.Functions.WebSearchToTsQuery("english", term)))
+                .ThenByDescending(e => e.SentAtUtc)
+                .Take(HybridK).Select(e => e.Id).ToListAsync(ct);
+
+            var queryVec = await _embeddings!.EmbedAsync(term, ct);
+            List<Guid> vecIds = new();
+            if (queryVec.Length > 0)
+            {
+                var qv = new Pgvector.Vector(queryVec);
+                vecIds = await structured
+                    .Where(e => e.Embedding != null)
+                    .OrderBy(e => e.Embedding!.CosineDistance(qv))
+                    .Take(HybridK).Select(e => e.Id).ToListAsync(ct);
+            }
+            if (vecIds.Count == 0) return null; // nothing embedded yet → lexical path
+
+            var scores = new Dictionary<Guid, double>();
+            for (var i = 0; i < lexIds.Count; i++)
+                scores[lexIds[i]] = scores.GetValueOrDefault(lexIds[i]) + 1.0 / (RrfConstant + i + 1);
+            for (var i = 0; i < vecIds.Count; i++)
+                scores[vecIds[i]] = scores.GetValueOrDefault(vecIds[i]) + 1.0 / (RrfConstant + i + 1);
+
+            var fused = scores.OrderByDescending(kv => kv.Value).Select(kv => kv.Key).ToList();
+            var pageIds = fused.Skip((r.Page - 1) * r.PageSize).Take(r.PageSize).ToList();
+            if (pageIds.Count == 0 && r.Page > 1) return null; // deep page → lexical paging
+
+            var headlineOpts =
+                $"StartSel={(char)0xE000},StopSel={(char)0xE001},MaxWords=16,MinWords=5,ShortWord=2,HighlightAll=false";
+            var rows = await _db.Emails.AsNoTracking()
+                .Where(e => pageIds.Contains(e.Id))
+                .Select(e => new EmailSummaryDto(
+                    e.Id, e.GmailMessageId, e.Subject, e.Snippet,
+                    e.Sender!.Address, e.Sender.DisplayName, e.SentAtUtc,
+                    e.IsUnread, e.IsStarred, e.HasAttachments, e.SizeEstimateBytes, e.Category,
+                    e.HasListUnsubscribe, e.SupportsOneClickUnsubscribe,
+                    EF.Functions.WebSearchToTsQuery("english", term).GetResultHeadline("english", e.BodyText ?? "", headlineOpts)))
+                .ToListAsync(ct);
+            var byId = rows.ToDictionary(x => x.Id);
+            var items = pageIds.Where(byId.ContainsKey).Select(id => byId[id]).ToList();
+
+            return new PagedResult<EmailSummaryDto>
+            {
+                Items = items,
+                Page = r.Page,
+                PageSize = r.PageSize,
+                // Semantic recall can exceed the lexical match count.
+                TotalCount = Math.Max(lexicalTotal, fused.Count)
+            };
+        }
+        catch
+        {
+            return null; // AI must never break search — degrade to lexical
+        }
+    }
 }

tests/InboxIntel.IntegrationTests/FeatureFlagTests.cs

@@ -1,76 +0,0 @@
-using FluentAssertions;
-using InboxIntel.Application.Abstractions;
-using InboxIntel.Domain.Entities;
-using InboxIntel.Infrastructure.Features;
-using InboxIntel.Infrastructure.Persistence;
-using Microsoft.EntityFrameworkCore;
-using Microsoft.Extensions.Caching.Memory;
-using Xunit;
-
-namespace InboxIntel.IntegrationTests;
-
-/// <summary>
-/// Feature-flag + AI-gate contracts (docs/discovery/multi-provider/04):
-/// flags are FAIL-CLOSED, and the admin master switch (ai.enabled) beats any user opt-in.
-/// </summary>
-public class FeatureFlagTests
-{
-    private sealed class FakeCurrentUser : ICurrentUser
-    {
-        public Guid UserId { get; set; }
-        public bool IsAuthenticated => UserId != Guid.Empty;
-    }
-
-    private static AppDbContext NewDb(string name) =>
-        new(new DbContextOptionsBuilder<AppDbContext>().UseInMemoryDatabase(name).Options, new FakeCurrentUser());
-
-    private static FeatureFlagService Flags(AppDbContext db) =>
-        new(db, new MemoryCache(new MemoryCacheOptions()));
-
-    [Fact]
-    public async Task Unknown_flag_is_disabled_fail_closed()
-    {
-        using var db = NewDb(nameof(Unknown_flag_is_disabled_fail_closed));
-        (await Flags(db).IsEnabledAsync("does.not.exist")).Should().BeFalse();
-    }
-
-    [Fact]
-    public async Task Enabled_flag_reads_true_disabled_reads_false()
-    {
-        using var db = NewDb(nameof(Enabled_flag_reads_true_disabled_reads_false));
-        db.FeatureFlags.AddRange(
-            new FeatureFlag { Key = "on.flag", Enabled = true },
-            new FeatureFlag { Key = "off.flag", Enabled = false });
-        await db.SaveChangesAsync();
-        var flags = Flags(db);
-        (await flags.IsEnabledAsync("on.flag")).Should().BeTrue();
-        (await flags.IsEnabledAsync("off.flag")).Should().BeFalse();
-    }
-
-    [Fact]
-    public async Task Ai_gate_master_flag_off_beats_user_opt_in()
-    {
-        using var db = NewDb(nameof(Ai_gate_master_flag_off_beats_user_opt_in));
-        var user = Guid.NewGuid();
-        db.FeatureFlags.Add(new FeatureFlag { Key = AiGate.MasterFlag, Enabled = false });
-        db.UserSettings.Add(new UserSetting { UserId = user, AiOptIn = true });
-        await db.SaveChangesAsync();
-
-        (await new AiGate(Flags(db), db).IsAiEnabledForUserAsync(user)).Should().BeFalse();
-    }
-
-    [Fact]
-    public async Task Ai_gate_flag_on_defaults_to_opted_in_but_respects_opt_out()
-    {
-        using var db = NewDb(nameof(Ai_gate_flag_on_defaults_to_opted_in_but_respects_opt_out));
-        var optedOut = Guid.NewGuid();
-        var noRow = Guid.NewGuid();
-        db.FeatureFlags.Add(new FeatureFlag { Key = AiGate.MasterFlag, Enabled = true });
-        db.UserSettings.Add(new UserSetting { UserId = optedOut, AiOptIn = false });
-        await db.SaveChangesAsync();
-        var gate = new AiGate(Flags(db), db);
-
-        (await gate.IsAiEnabledForUserAsync(noRow)).Should().BeTrue("no settings row = default opt-in");
-        (await gate.IsAiEnabledForUserAsync(optedOut)).Should().BeFalse("explicit opt-out wins while the flag is on");
-    }
-}

tests/InboxIntel.IntegrationTests/LiveDbSearchTests.cs

@@ -123,4 +123,54 @@ public class LiveDbSearchTests
         }
         finally { await CleanupAsync(opts, uid); }
     }
+
+    private sealed class DirectionalFakeEmbeddings : IEmbeddingProvider
+    {
+        public bool IsAvailable => true;
+        public Task<float[]> EmbedAsync(string text, CancellationToken ct = default)
+        {
+            // Deterministic "semantics": anything fruit-flavoured points one way, else the other.
+            var v = new float[768];
+            if (text.Contains("banana") || text.Contains("tropical")) v[0] = 1; else v[1] = 1;
+            return Task.FromResult(v);
+        }
+        public async Task<IReadOnlyList<float[]>> EmbedBatchAsync(IReadOnlyList<string> texts, CancellationToken ct = default)
+        {
+            var list = new List<float[]>();
+            foreach (var t in texts) list.Add(await EmbedAsync(t, ct));
+            return list;
+        }
+    }
+
+    [Fact]
+    public async Task Hybrid_search_surfaces_semantic_match_with_zero_keyword_overlap()
+    {
+        if (Conn is null) return;
+        var opts = Options();
+        var uid = await SeedAsync(opts);
+        try
+        {
+            var embeddings = new DirectionalFakeEmbeddings();
+            using (var prep = new AppDbContext(opts, new FakeCurrentUser()))
+            {
+                // "Weekly notes" gets a fruit-direction embedding (semantically related to the
+                // query); "Invoice March" points elsewhere. Neither subject contains "banana".
+                var near = await prep.Emails.FirstAsync(e => e.UserId == uid && e.Subject == "Weekly notes");
+                near.Embedding = new Vector(await embeddings.EmbedAsync("tropical"));
+                var far = await prep.Emails.FirstAsync(e => e.UserId == uid && e.Subject == "Invoice March");
+                far.Embedding = new Vector(await embeddings.EmbedAsync("finance"));
+                await prep.SaveChangesAsync();
+            }
+
+            using var ctx = new AppDbContext(opts, new FakeCurrentUser { UserId = uid });
+            var res = await new SearchService(ctx, embeddings)
+                .SearchAsync(uid, GmailQueryParser.Parse("banana", 1, 10));
+
+            // Zero lexical hits for "banana" — hybrid must still surface the semantically
+            // nearest email, ranked first.
+            res.Items.Should().NotBeEmpty("semantic recall should fire with zero keyword overlap");
+            res.Items[0].Subject.Should().Be("Weekly notes");
+        }
+        finally { await CleanupAsync(opts, uid); }
+    }
 }