@polymorphism-tech/morph-spec 4.16.0 → 4.17.0

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -1,18 +1,18 @@
 # Next.js 15 Patterns Standard
 
-> **Scope:** nextjs-supabase
+> **Scope:** nextjs-neon
 > **Layer:** 2 (on keyword)
 > **Keywords:** nextjs, react, app router, server component, client component
 > **Load When:** nextjs keywords detected
 
-Stack: Next.js 15 + Supabase + .NET Backend
+Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 
 ## Core Rules
 
 - ALWAYS use App Router (not Pages Router)
 - Default to Server Components -- add `'use client'` only when needed
 - ALWAYS colocate loading.tsx and error.tsx with page.tsx
-- NEVER call Supabase directly from client -- use Route Handlers as BFF
+- NEVER call the database directly from client -- use Route Handlers as BFF
 - ALWAYS validate inputs with Zod on both client and server
 - Use TypeScript strict mode (`"strict": true`)
 
@@ -64,39 +64,49 @@ export default function Error({ error, reset }: { error: Error; reset: () => voi
 ## Route Handlers (BFF Pattern)
 
 ```ts
-// app/api/documents/route.ts
-import { createClient } from "@/lib/supabase/server";
+// app/api/documents/route.ts — BFF pattern (delegates to .NET API)
+import { auth } from "@clerk/nextjs/server";
 import { NextResponse } from "next/server";
 import { z } from "zod";
 
+const API_URL = process.env.API_URL!; // .NET backend
+
 const CreateSchema = z.object({
   title: z.string().min(1).max(200),
   content: z.string().min(1),
 });
 
 export async function GET() {
-  const supabase = await createClient();
-  const { data: { user } } = await supabase.auth.getUser();
-  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-  const { data, error } = await supabase.from("documents").select("*");
-  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
-  return NextResponse.json(data);
+  const { userId, getToken } = await auth();
+  if (!userId) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+
+  const token = await getToken();
+  const res = await fetch(`${API_URL}/api/documents`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  return NextResponse.json(await res.json());
 }
 
 export async function POST(request: Request) {
-  const supabase = await createClient();
-  const { data: { user } } = await supabase.auth.getUser();
-  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  const { userId, getToken } = await auth();
+  if (!userId) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+
   const parsed = CreateSchema.safeParse(await request.json());
   if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
-  const { data, error } = await supabase
-    .from("documents").insert({ ...parsed.data, user_id: user.id }).select().single();
-  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
-  return NextResponse.json(data, { status: 201 });
+
+  const token = await getToken();
+  const res = await fetch(`${API_URL}/api/documents`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(parsed.data),
+  });
+  return NextResponse.json(await res.json(), { status: res.status });
 }
 ```
 
-## React Query + Supabase
+> **Rule:** Route handlers act as BFF (Backend-For-Frontend) — they delegate to the .NET API. Database access lives in the .NET backend via EF Core, never in Next.js route handlers.
+
+## React Query + Neon
 
 ```tsx
 // providers/query-provider.tsx
@@ -190,26 +200,26 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | Wrong | Right | Why |
 |-------|-------|-----|
 | `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
-| Direct Supabase from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
+| Direct DB from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
 | `any` for API responses | Zod schema + infer | No runtime safety |
 | Missing loading.tsx | Colocate with page.tsx | Blank page during load |
 | `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
 | Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
 | shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |
-
-## TypeScript Strict Mode (Required)
-
-Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
-agent-assisted development because agents rely on compiler errors to self-correct.
-Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true
-  }
-}
-```
-
-Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.
+
+## TypeScript Strict Mode (Required)
+
+Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
+agent-assisted development because agents rely on compiler errors to self-correct.
+Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.

package/framework/standards/infrastructure/docker/easypanel-deploy.md

@@ -1,11 +1,11 @@
 # EasyPanel Deployment Standard
 
-> **Scope:** nextjs-supabase
+> **Scope:** nextjs-neon
 > **Layer:** 2 (on keyword)
 > **Keywords:** easypanel, docker, deploy, deployment, container
 > **Load When:** easypanel or docker deployment keywords detected
 
-Stack: Next.js 15 + Supabase + .NET Backend
+Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 
 ## Core Rules
 
@@ -115,17 +115,13 @@ SSL via Let's Encrypt is automatic. Force HTTPS enabled by default.
 ```env
 ASPNETCORE_ENVIRONMENT=Production
 ASPNETCORE_URLS=http://+:8080
-ConnectionStrings__DefaultConnection=Host=...;Database=...;Username=...;Password=...
-Supabase__Url=https://xxx.supabase.co
-Supabase__ServiceRoleKey=eyJ...
-Supabase__JwtSecret=your-jwt-secret
+ConnectionStrings__DefaultConnection=Host=ep-xxx.us-east-2.aws.neon.tech;Database=neondb;Username=...;Password=...;SslMode=Require
 ```
 
 ### Next.js Frontend
 
 ```env
-NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require
 NEXT_PUBLIC_API_URL=https://api.example.com
 ```
 

package/framework/standards/infrastructure/neon/neon-pgrag.md

@@ -0,0 +1,239 @@
+# Neon pgrag Standard
+
+> **Scope:** neon
+> **Layer:** 2 (on keyword)
+> **Keywords:** pgrag, rag, chunking, embedding, reranking, retrieval
+> **Load When:** pgrag or in-database RAG keywords detected
+
+Stack: Neon Serverless Postgres
+
+## Core Rules
+
+- pgrag is EXPERIMENTAL -- API may change between Neon releases
+- ALWAYS enable unstable extensions before installing: `SET neon.allow_unstable_extensions='true'`
+- Use pgrag for simple, self-contained RAG pipelines (PDF ingestion, chunking, search)
+- Use application-level RAG (Semantic Kernel + pgvector) for complex workflows requiring custom logic, multi-model orchestration, or .NET integration
+- NEVER use pgrag local embeddings (384 dims) when your application uses a different embedding model -- dimension mismatch breaks search
+
+## Install pgrag
+
+```sql
+-- Enable unstable extensions (required)
+SET neon.allow_unstable_extensions='true';
+
+-- Core extension
+CREATE EXTENSION IF NOT EXISTS rag CASCADE;
+
+-- Local embedding model (bge-small-en-v1.5, 384 dimensions, 33M params)
+CREATE EXTENSION IF NOT EXISTS rag_bge_small_en_v15 CASCADE;
+
+-- Local reranker (jina-reranker-v1-tiny-en, 33M params)
+CREATE EXTENSION IF NOT EXISTS rag_jina_reranker_v1_tiny_en CASCADE;
+```
+
+## Text Extraction
+
+Extract text from binary documents directly in SQL:
+
+```sql
+-- Extract text from PDF
+SELECT rag.text_from_pdf(pg_read_binary_file('/path/to/document.pdf'));
+
+-- Extract text from DOCX
+SELECT rag.text_from_docx(pg_read_binary_file('/path/to/document.docx'));
+
+-- Convert HTML to Markdown
+SELECT rag.markdown_from_html('<h1>Title</h1><p>Content here</p>');
+```
+
+### From a Documents Table
+
+```sql
+CREATE TABLE raw_documents (
+  id SERIAL PRIMARY KEY,
+  filename TEXT NOT NULL,
+  content BYTEA NOT NULL,
+  extracted_text TEXT
+);
+
+-- Extract text on insert
+UPDATE raw_documents
+SET extracted_text = rag.text_from_pdf(content)
+WHERE filename LIKE '%.pdf' AND extracted_text IS NULL;
+```
+
+## Chunking Strategies
+
+### Character-Based Chunking
+
+Splits text by character count with overlap for context continuity:
+
+```sql
+-- Split into chunks of 1000 chars with 200 char overlap
+SELECT unnest(
+  rag.chunks_by_character_count(
+    'Your long document text here...',
+    1000,   -- max_chars per chunk
+    200     -- overlap chars
+  )
+);
+```
+
+### Token-Based Chunking
+
+Uses the bge-small-en-v1.5 tokenizer for model-aware splitting:
+
+```sql
+-- Split into chunks of 512 tokens with 50 token overlap
+SELECT unnest(
+  rag_bge_small_en_v15.chunks_by_token_count(
+    'Your long document text here...',
+    512,    -- max_tokens per chunk
+    50      -- overlap tokens
+  )
+);
+```
+
+## Embedding Generation
+
+### Local Embeddings (bge-small-en-v1.5)
+
+Zero-cost, runs on the database server. Produces 384-dimension vectors:
+
+```sql
+-- Embedding for a document passage (includes "passage:" prefix internally)
+SELECT rag_bge_small_en_v15.embedding_for_passage('Neon is a serverless Postgres platform');
+
+-- Embedding for a search query (includes "query:" prefix internally)
+SELECT rag_bge_small_en_v15.embedding_for_query('What is Neon?');
+```
+
+### OpenAI Embeddings (text-embedding-3-small)
+
+Remote API call, produces 1536-dimension vectors:
+
+```sql
+-- Set API key (per session)
+SET neon.ai_api_key = 'sk-...';
+
+-- Generate embedding via OpenAI
+SELECT rag.openai_text_embedding_3_small('Neon is a serverless Postgres platform');
+```
+
+## Full RAG Pipeline Example
+
+```sql
+-- 1. Create chunks table
+CREATE TABLE chunks (
+  id SERIAL PRIMARY KEY,
+  document_id INT REFERENCES raw_documents(id),
+  chunk_text TEXT NOT NULL,
+  embedding vector(384)
+);
+
+-- 2. Chunk and embed a document
+WITH doc AS (
+  SELECT id, rag.text_from_pdf(content) AS full_text
+  FROM raw_documents WHERE id = 1
+),
+chunked AS (
+  SELECT doc.id AS document_id, unnest(
+    rag.chunks_by_character_count(doc.full_text, 1000, 200)
+  ) AS chunk_text
+  FROM doc
+)
+INSERT INTO chunks (document_id, chunk_text, embedding)
+SELECT document_id, chunk_text,
+  rag_bge_small_en_v15.embedding_for_passage(chunk_text)
+FROM chunked;
+
+-- 3. Create HNSW index
+CREATE INDEX idx_chunks_embedding ON chunks
+  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
+```
+
+## Similarity Search
+
+```sql
+-- Find top 10 similar chunks
+SELECT id, chunk_text,
+  1 - (embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')) AS similarity
+FROM chunks
+ORDER BY embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')
+LIMIT 10;
+```
+
+## Reranking
+
+Reranking refines initial vector search results using a cross-encoder model for higher accuracy:
+
+```sql
+-- Rerank top 10 vector results down to top 5
+WITH vector_matches AS (
+  SELECT id, chunk_text,
+    1 - (embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')) AS similarity
+  FROM chunks
+  ORDER BY embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')
+  LIMIT 10
+)
+SELECT id, chunk_text, similarity,
+  rag_jina_reranker_v1_tiny_en.rerank_distance('What is Neon?', chunk_text) AS rerank_score
+FROM vector_matches
+ORDER BY rerank_score ASC
+LIMIT 5;
+```
+
+## LLM Integration in SQL
+
+Send context + question to an LLM directly from SQL:
+
+```sql
+-- Set API key
+SET neon.ai_api_key = 'sk-...';
+
+-- Ask a question with retrieved context
+WITH context AS (
+  SELECT string_agg(chunk_text, E'\n---\n') AS combined_context
+  FROM (
+    SELECT chunk_text FROM chunks
+    ORDER BY embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')
+    LIMIT 5
+  ) top_chunks
+)
+SELECT rag.openai_chat_completion(
+  json_build_object(
+    'model', 'gpt-4o',
+    'messages', json_build_array(
+      json_build_object('role', 'system', 'content',
+        'Answer based on the provided context. If unsure, say so.'),
+      json_build_object('role', 'user', 'content',
+        format('Context:\n%s\n\nQuestion: What is Neon?', context.combined_context))
+    )
+  )
+) FROM context;
+```
+
+## When to Use pgrag vs Application-Level RAG
+
+| Factor | pgrag (In-Database) | SK + pgvector (Application) |
+|--------|---------------------|----------------------------|
+| Setup complexity | Minimal -- SQL only | Requires .NET service layer |
+| Embedding model | Local (384d) or OpenAI | Any model via SK connectors |
+| Reranking | Built-in (Jina) | Custom implementation |
+| Custom logic | Limited to SQL | Full C# flexibility |
+| Multi-model orchestration | Not supported | Native SK capability |
+| Production readiness | Experimental | Stable (SK GA) |
+| Cost | Zero for local models | API costs for remote models |
+| Best for | Prototyping, simple RAG, SQL-only environments | Production .NET applications, complex pipelines |
+
+**Recommendation:** Start with pgrag for prototyping and validation. Migrate to Semantic Kernel + pgvector for production .NET applications that need custom retrieval logic, multi-model orchestration, or integration with MAF agents.
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| Missing `neon.allow_unstable_extensions` | `SET neon.allow_unstable_extensions='true'` | pgrag won't install without it |
+| Mixing local (384d) and OpenAI (1536d) embeddings | Use one model consistently per column | Dimension mismatch breaks similarity search |
+| No HNSW index on chunks table | Create index after initial data load | Full table scan on every search |
+| Using pgrag in production without testing | Validate with representative data first | Extension is experimental, may change |
+| Storing API key in SQL scripts | Use session variables or environment config | Keys in scripts leak to version control |

package/framework/standards/infrastructure/neon/neon-pgvector.md

@@ -0,0 +1,236 @@
+# Neon pgvector Standard
+
+> **Scope:** neon, dotnet-vsa
+> **Layer:** 1 (on scope)
+> **Keywords:** pgvector, vector, embeddings, similarity search, HNSW, cosine
+> **Load When:** pgvector or embedding keywords detected
+
+Stack: .NET VSA + Neon Serverless Postgres
+
+## Core Rules
+
+- ALWAYS use HNSW indexes for production (faster queries, no training data required)
+- ALWAYS match vector dimensions to your embedding model (e.g., 1536 for text-embedding-3-small)
+- NEVER store embeddings without an index -- full table scan at query time
+- ALWAYS call `UseVector()` on `NpgsqlDataSourceBuilder` before using vector types
+- ALWAYS register the `vector` extension in `OnModelCreating`
+- Use `ReadOnlyMemory<float>` for vector properties in EF Core entities
+
+## Enable pgvector
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+## EF Core Entity Mapping
+
+### NuGet Package
+
+```bash
+dotnet add package Pgvector.EntityFrameworkCore
+```
+
+### Entity Definition
+
+```csharp
+using System.ComponentModel.DataAnnotations.Schema;
+using Pgvector;
+
+public class Document
+{
+    public Guid Id { get; set; }
+    public string Title { get; set; } = string.Empty;
+    public string Content { get; set; } = string.Empty;
+    public string? Metadata { get; set; }
+
+    [Column(TypeName = "vector(1536)")]
+    public Vector? Embedding { get; set; }
+
+    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
+}
+```
+
+### IEntityTypeConfiguration
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+
+public class DocumentConfiguration : IEntityTypeConfiguration<Document>
+{
+    public void Configure(EntityTypeBuilder<Document> builder)
+    {
+        builder.ToTable("documents");
+        builder.HasKey(d => d.Id);
+        builder.Property(d => d.Id).HasDefaultValueSql("gen_random_uuid()");
+        builder.Property(d => d.Title).IsRequired();
+        builder.Property(d => d.Content).IsRequired();
+        builder.Property(d => d.Metadata).HasColumnType("jsonb");
+        builder.Property(d => d.Embedding).HasColumnType("vector(1536)");
+        builder.Property(d => d.CreatedAt).HasDefaultValueSql("now()");
+
+        // HNSW index for cosine similarity
+        builder.HasIndex(d => d.Embedding)
+            .HasMethod("hnsw")
+            .HasOperators("vector_cosine_ops")
+            .HasStorageParameter("m", 16)
+            .HasStorageParameter("ef_construction", 64);
+    }
+}
+```
+
+### DbContext Setup
+
+```csharp
+public class AppDbContext : DbContext
+{
+    public DbSet<Document> Documents => Set<Document>();
+
+    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        modelBuilder.HasPostgresExtension("vector");
+        modelBuilder.ApplyConfiguration(new DocumentConfiguration());
+    }
+}
+
+// Registration with vector support
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseNpgsql(connectionString, npgsql => npgsql.UseVector()));
+```
+
+## HNSW Index Creation (Raw SQL)
+
+```sql
+-- Cosine distance (most common for normalized embeddings)
+CREATE INDEX idx_documents_embedding ON documents
+  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
+
+-- L2 (Euclidean) distance
+CREATE INDEX idx_documents_embedding_l2 ON documents
+  USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);
+
+-- Tune search accuracy per session
+SET hnsw.ef_search = 100;
+```
+
+### HNSW Parameters
+
+| Parameter | Default | Tuning |
+|-----------|---------|--------|
+| `m` | 16 | Higher = better recall, more memory |
+| `ef_construction` | 64 | Higher = better index quality, slower build |
+| `ef_search` | 40 | Higher = better recall at query time |
+
+## Distance Operators
+
+| Operator | Function | Index Ops | Use Case |
+|----------|----------|-----------|----------|
+| `<=>` | Cosine distance | `vector_cosine_ops` | Normalized embeddings (most common) |
+| `<->` | L2 (Euclidean) | `vector_l2_ops` | Spatial/positional data |
+| `<#>` | Inner product (neg) | `vector_ip_ops` | Pre-normalized, max similarity |
+
+## Similarity Search
+
+### SQL Function
+
+```sql
+CREATE OR REPLACE FUNCTION match_documents(
+  query_embedding vector(1536),
+  match_threshold float DEFAULT 0.78,
+  match_count int DEFAULT 10
+) RETURNS TABLE (id uuid, title text, content text, similarity float)
+LANGUAGE sql STABLE AS $$
+  SELECT d.id, d.title, d.content,
+    1 - (d.embedding <=> query_embedding) AS similarity
+  FROM documents d
+  WHERE 1 - (d.embedding <=> query_embedding) > match_threshold
+  ORDER BY d.embedding <=> query_embedding
+  LIMIT match_count;
+$$;
+```
+
+### C# Repository
+
+```csharp
+using Pgvector;
+
+public sealed class DocumentRepository(AppDbContext db)
+{
+    public async Task StoreEmbeddingAsync(
+        Guid documentId, float[] embedding, CancellationToken ct = default)
+    {
+        await db.Database.ExecuteSqlInterpolatedAsync(
+            $"UPDATE documents SET embedding = {new Vector(embedding)} WHERE id = {documentId}", ct);
+    }
+
+    public async Task<List<DocumentMatch>> SearchSimilarAsync(
+        float[] queryEmbedding, int limit = 10, float threshold = 0.78f,
+        CancellationToken ct = default)
+    {
+        return await db.Database.SqlQuery<DocumentMatch>($"""
+            SELECT id, title, content,
+              1 - (embedding <=> {new Vector(queryEmbedding)}::vector) AS similarity
+            FROM documents
+            WHERE 1 - (embedding <=> {new Vector(queryEmbedding)}::vector) > {threshold}
+            ORDER BY embedding <=> {new Vector(queryEmbedding)}::vector
+            LIMIT {limit}
+            """).ToListAsync(ct);
+    }
+}
+
+public record DocumentMatch(Guid Id, string Title, string Content, float Similarity);
+```
+
+## Hybrid Search (Vector + Full-Text)
+
+```sql
+CREATE OR REPLACE FUNCTION hybrid_search(
+  query_text text,
+  query_embedding vector(1536),
+  match_count int DEFAULT 10,
+  text_weight float DEFAULT 0.3,
+  vector_weight float DEFAULT 0.7
+) RETURNS TABLE (id uuid, title text, content text, score float)
+LANGUAGE sql STABLE AS $$
+  WITH vector_results AS (
+    SELECT id, title, content,
+      1 - (embedding <=> query_embedding) AS vector_score
+    FROM documents
+    ORDER BY embedding <=> query_embedding LIMIT match_count * 2
+  ),
+  text_results AS (
+    SELECT id, title, content,
+      ts_rank(to_tsvector('english', content), plainto_tsquery('english', query_text)) AS text_score
+    FROM documents
+    WHERE to_tsvector('english', content) @@ plainto_tsquery('english', query_text)
+    LIMIT match_count * 2
+  )
+  SELECT COALESCE(v.id, t.id), COALESCE(v.title, t.title), COALESCE(v.content, t.content),
+    (COALESCE(v.vector_score, 0) * vector_weight + COALESCE(t.text_score, 0) * text_weight) AS score
+  FROM vector_results v FULL OUTER JOIN text_results t ON v.id = t.id
+  ORDER BY score DESC LIMIT match_count;
+$$;
+```
+
+## Npgsql Vector Type Handler
+
+The `Pgvector.EntityFrameworkCore` package automatically registers the vector type handler when you call `UseVector()`. For raw Npgsql (without EF Core):
+
+```csharp
+var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
+dataSourceBuilder.UseVector();
+await using var dataSource = dataSourceBuilder.Build();
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| No index on embedding column | HNSW index | Full table scan, extremely slow |
+| `ORDER BY similarity DESC` | `ORDER BY embedding <=> query ASC` | Operators return distance, not similarity |
+| Missing `UseVector()` | Call on `NpgsqlDataSourceBuilder` | Npgsql cannot map vector types without it |
+| Mixing embedding dimensions | Consistent dimensions per column | Dimension mismatch causes runtime errors |
+| `float[]` for EF Core property | `Vector` from Pgvector package | EF Core mapping requires the Pgvector type |
+| No `HasPostgresExtension("vector")` | Add in `OnModelCreating` | Extension must be declared for migrations |