@polymorphism-tech/morph-spec 4.16.0 → 4.17.0

package/framework/standards/infrastructure/neon/neon-semantic-kernel.md

@@ -0,0 +1,310 @@
+# Neon Semantic Kernel Vector Store Standard
+
+> **Scope:** neon, dotnet-vsa
+> **Layer:** 2 (on keyword)
+> **Keywords:** semantic kernel, vector store, PostgresVectorStore, VectorStoreTextSearch, MAF
+> **Load When:** semantic kernel postgres vector keywords detected
+
+Stack: .NET VSA + Neon Serverless Postgres + Semantic Kernel
+
+## Core Rules
+
+- ALWAYS call `UseVector()` on `NpgsqlDataSourceBuilder` -- without it the vector store fails silently
+- ALWAYS use `AddPostgresVectorStore()` for DI registration -- handles datasource lifecycle
+- NEVER mix pgvector-dotnet `Vector` type with SK `ReadOnlyMemory<float>` -- SK uses its own mapping
+- ALWAYS annotate data model properties with `[VectorStoreKey]`, `[VectorStoreData]`, `[VectorStoreVector]`
+- Use `PostgresCollection<TKey, TRecord>` for typed collection access
+
+## NuGet Packages
+
+```bash
+dotnet add package Microsoft.SemanticKernel.Connectors.PgVector --prerelease
+dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI
+dotnet add package Npgsql
+```
+
+## PostgresVectorStore Initialization
+
+### Via Dependency Injection (Recommended)
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+using Npgsql;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Option 1: Connection string (UseVector applied automatically)
+builder.Services.AddPostgresVectorStore(
+    builder.Configuration.GetConnectionString("DefaultConnection")!);
+
+// Option 2: Manual NpgsqlDataSource (full control)
+builder.Services.AddSingleton<NpgsqlDataSource>(sp =>
+{
+    var dataSourceBuilder = new NpgsqlDataSourceBuilder(
+        builder.Configuration.GetConnectionString("DefaultConnection"));
+    dataSourceBuilder.UseVector();
+    return dataSourceBuilder.Build();
+});
+builder.Services.AddPostgresVectorStore();
+```
+
+### Direct Construction
+
+```csharp
+using Microsoft.SemanticKernel.Connectors.PgVector;
+using Npgsql;
+
+var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
+dataSourceBuilder.UseVector();
+var dataSource = dataSourceBuilder.Build();
+
+var vectorStore = new PostgresVectorStore(dataSource, ownsDataSource: true);
+```
+
+## Data Model Definition
+
+Annotate your record type with SK vector store attributes:
+
+```csharp
+using System;
+using Microsoft.Extensions.VectorData;
+
+public class KnowledgeEntry
+{
+    [VectorStoreKey(StorageName = "id")]
+    public Guid Id { get; set; }
+
+    [VectorStoreData(StorageName = "title")]
+    public string Title { get; set; } = string.Empty;
+
+    [VectorStoreData(StorageName = "content")]
+    public string Content { get; set; } = string.Empty;
+
+    [VectorStoreData(StorageName = "source")]
+    public string? Source { get; set; }
+
+    [VectorStoreData(StorageName = "created_at")]
+    public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
+
+    [VectorStoreVector(
+        Dimensions: 1536,
+        DistanceFunction = DistanceFunction.CosineDistance,
+        IndexKind = IndexKind.Hnsw,
+        StorageName = "embedding")]
+    public ReadOnlyMemory<float>? Embedding { get; set; }
+}
+```
+
+This maps to the following Postgres table (auto-created by `EnsureCollectionExistsAsync`):
+
+```sql
+CREATE TABLE IF NOT EXISTS public."knowledge_entries" (
+    "id" UUID PRIMARY KEY NOT NULL,
+    "title" TEXT,
+    "content" TEXT,
+    "source" TEXT,
+    "created_at" TIMESTAMPTZ,
+    "embedding" VECTOR(1536)
+);
+```
+
+## Collection Operations
+
+```csharp
+using Microsoft.SemanticKernel.Connectors.PgVector;
+
+// Get a typed collection
+var collection = vectorStore.GetCollection<Guid, KnowledgeEntry>("knowledge_entries");
+
+// Create table if it doesn't exist (includes HNSW index)
+await collection.EnsureCollectionExistsAsync();
+
+// Upsert a record
+var entry = new KnowledgeEntry
+{
+    Id = Guid.NewGuid(),
+    Title = "Neon Overview",
+    Content = "Neon is a serverless Postgres platform...",
+    Source = "docs",
+    Embedding = new ReadOnlyMemory<float>(embeddingVector)
+};
+await collection.UpsertAsync(entry);
+
+// Get by key
+var retrieved = await collection.GetAsync(entry.Id);
+
+// Delete
+await collection.DeleteAsync(entry.Id);
+```
+
+## Embedding Generation with OpenAI
+
+```csharp
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using Microsoft.SemanticKernel.Embeddings;
+
+// Register embedding service
+builder.Services.AddOpenAITextEmbeddingGeneration(
+    modelId: "text-embedding-3-small",
+    apiKey: builder.Configuration["OpenAI:ApiKey"]!);
+
+// Generate embeddings
+public class EmbeddingService(ITextEmbeddingGenerationService embeddingService)
+{
+    public async Task<ReadOnlyMemory<float>> GenerateAsync(string text)
+    {
+        var embeddings = await embeddingService.GenerateEmbeddingsAsync([text]);
+        return embeddings[0];
+    }
+
+    public async Task<IList<ReadOnlyMemory<float>>> GenerateBatchAsync(IList<string> texts)
+    {
+        return await embeddingService.GenerateEmbeddingsAsync(texts);
+    }
+}
+```
+
+## VectorStoreTextSearch Usage
+
+`VectorStoreTextSearch<T>` provides a high-level search API that automatically generates embeddings for queries:
+
+```csharp
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Data;
+
+// Create text search from collection + embedding service
+var textSearch = new VectorStoreTextSearch<KnowledgeEntry>(
+    collection,
+    embeddingGenerationService);
+
+// Search with natural language
+var query = "How does Neon branching work?";
+KernelSearchResults<TextSearchResult> results = await textSearch.GetTextSearchResultsAsync(
+    query, new() { Top = 5, Skip = 0 });
+
+await foreach (TextSearchResult result in results.Results)
+{
+    Console.WriteLine($"Name:  {result.Name}");
+    Console.WriteLine($"Value: {result.Value}");
+    Console.WriteLine($"Link:  {result.Link}");
+}
+```
+
+### Use as Kernel Plugin (RAG in Prompts)
+
+```csharp
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.PromptTemplates.Handlebars;
+
+var kernel = builder.Build();
+
+// Register text search as a plugin
+var searchPlugin = textSearch.CreateWithGetTextSearchResults("KnowledgeSearch");
+kernel.Plugins.Add(searchPlugin);
+
+// Use in prompt with automatic retrieval
+var promptTemplate = """
+    {{#with (KnowledgeSearch-GetTextSearchResults query)}}
+      {{#each this}}
+        Name: {{Name}}
+        Value: {{Value}}
+        ---
+      {{/each}}
+    {{/with}}
+
+    Based on the above context, answer: {{query}}
+    """;
+
+var function = KernelFunctionFactory.CreateFromPrompt(
+    new PromptTemplateConfig
+    {
+        Template = promptTemplate,
+        TemplateFormat = "handlebars"
+    },
+    new HandlebarsPromptTemplateFactory());
+
+var result = await kernel.InvokeAsync(function,
+    new KernelArguments { ["query"] = "How does Neon branching work?" });
+```
+
+## Integration with MAF Agents
+
+Use the vector store as a plugin for ChatCompletionAgent to give agents vector memory:
+
+```csharp
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Data;
+
+// Build kernel with vector search plugin
+var kernelBuilder = Kernel.CreateBuilder();
+kernelBuilder.AddOpenAIChatCompletion("gpt-4o", apiKey);
+kernelBuilder.AddOpenAITextEmbeddingGeneration("text-embedding-3-small", apiKey);
+var kernel = kernelBuilder.Build();
+
+// Register vector search as a kernel plugin
+var searchPlugin = textSearch.CreateWithGetTextSearchResults("KnowledgeBase");
+kernel.Plugins.Add(searchPlugin);
+
+// Create agent with vector memory
+var agent = new ChatCompletionAgent
+{
+    Name = "KnowledgeAgent",
+    Instructions = """
+        You are a knowledge assistant. Use the KnowledgeBase plugin to search for
+        relevant information before answering questions. Always cite your sources.
+        """,
+    Kernel = kernel,
+    Arguments = new KernelArguments(
+        new OpenAIPromptExecutionSettings { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })
+};
+
+// Agent automatically calls vector search when needed
+await foreach (var message in agent.InvokeAsync(chatHistory))
+{
+    Console.WriteLine(message.Content);
+}
+```
+
+## Service Registration Summary
+
+```csharp
+// Program.cs -- complete registration
+var builder = WebApplication.CreateBuilder(args);
+
+// 1. Vector store (Neon + pgvector)
+builder.Services.AddPostgresVectorStore(
+    builder.Configuration.GetConnectionString("DefaultConnection")!);
+
+// 2. Embedding generation
+builder.Services.AddOpenAITextEmbeddingGeneration(
+    modelId: "text-embedding-3-small",
+    apiKey: builder.Configuration["OpenAI:ApiKey"]!);
+
+// 3. Chat completion (for agents)
+builder.Services.AddOpenAIChatCompletion(
+    modelId: "gpt-4o",
+    apiKey: builder.Configuration["OpenAI:ApiKey"]!);
+
+// 4. Application services
+builder.Services.AddSingleton<EmbeddingService>();
+builder.Services.AddSingleton(sp =>
+{
+    var vectorStore = sp.GetRequiredService<PostgresVectorStore>();
+    return vectorStore.GetCollection<Guid, KnowledgeEntry>("knowledge_entries");
+});
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| Missing `UseVector()` on data source | Always call `dataSourceBuilder.UseVector()` | Vector type mapping fails without it |
+| Using `float[]` for vector property | `ReadOnlyMemory<float>` with `[VectorStoreVector]` | SK connector expects its own vector types |
+| No `StorageName` on attributes | Set `StorageName` for snake_case columns | C# PascalCase won't match Postgres columns |
+| Creating collection without `EnsureCollectionExistsAsync` | Call before first upsert/search | Table and index won't exist |
+| Hardcoded embedding dimensions | Match `Dimensions` to your model (1536 for ada-002/3-small) | Mismatch causes insertion errors |
+| Using pgvector-dotnet `Vector` with SK | Use `ReadOnlyMemory<float>` | SK has its own type mapping layer |

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

@@ -0,0 +1,186 @@
+# Neon Serverless Postgres Standard
+
+> **Scope:** neon
+> **Layer:** 0 (always load)
+> **Keywords:** neon, serverless postgres, branching, scale-to-zero, connection string, neonctl
+> **Load When:** neon stack detected
+
+Stack: .NET + Neon Serverless Postgres
+
+## Core Rules
+
+- ALWAYS use pooled connection strings (`-pooler` endpoint) for application traffic
+- ALWAYS use direct connection strings for migrations and schema changes
+- NEVER hardcode connection strings -- use environment variables
+- ALWAYS enable SSL (`SSL Mode=Require`) for all connections
+- ALWAYS configure retry policies for cold-start resilience
+- NEVER leave branches without expiration -- set TTL for dev/CI branches
+
+## Neon CLI Setup
+
+```bash
+# Install neonctl globally
+npm install -g neonctl
+
+# Authenticate (opens browser)
+neonctl auth
+
+# Verify connection
+neonctl projects list
+```
+
+## Connection Strings
+
+### Pooled vs Direct
+
+| Type | Hostname Pattern | Use Case |
+|------|-----------------|----------|
+| Pooled | `ep-xxxx-pooler.region.aws.neon.tech` | Application queries, high concurrency |
+| Direct | `ep-xxxx.region.aws.neon.tech` | Migrations, EF Core `dotnet ef`, advisory locks |
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `DATABASE_URL` | Pooled connection for application runtime |
+| `DATABASE_URL_UNPOOLED` | Direct connection for migrations and CLI tools |
+
+```ini
+# Pooled (application)
+DATABASE_URL="Host=ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech;Database=mydb;Username=myuser;Password=secret;SSL Mode=Require"
+
+# Direct (migrations)
+DATABASE_URL_UNPOOLED="Host=ep-cool-darkness-123456.us-east-2.aws.neon.tech;Database=mydb;Username=myuser;Password=secret;SSL Mode=Require"
+```
+
+## EF Core Configuration
+
+### appsettings.json
+
+```json
+{
+  "ConnectionStrings": {
+    "DefaultConnection": "Host=ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech;Database=mydb;Username=myuser;Password=secret;SSL Mode=Require;Trust Server Certificate=true",
+    "MigrationConnection": "Host=ep-cool-darkness-123456.us-east-2.aws.neon.tech;Database=mydb;Username=myuser;Password=secret;SSL Mode=Require;Trust Server Certificate=true"
+  }
+}
+```
+
+### DbContext Registration
+
+```csharp
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseNpgsql(
+        builder.Configuration.GetConnectionString("DefaultConnection"),
+        npgsqlOptions =>
+        {
+            npgsqlOptions.EnableRetryOnFailure(
+                maxRetryCount: 5,
+                maxRetryDelay: TimeSpan.FromSeconds(10),
+                errorCodesToAdd: null);
+            npgsqlOptions.CommandTimeout(30);
+        }));
+```
+
+### Design-Time Factory (for migrations using direct connection)
+
+```csharp
+public class AppDbContextFactory : IDesignTimeDbContextFactory<AppDbContext>
+{
+    public AppDbContext CreateDbContext(string[] args)
+    {
+        var configuration = new ConfigurationBuilder()
+            .AddJsonFile("appsettings.json")
+            .AddEnvironmentVariables()
+            .Build();
+
+        var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>();
+        optionsBuilder.UseNpgsql(
+            configuration.GetConnectionString("MigrationConnection"));
+
+        return new AppDbContext(optionsBuilder.Options);
+    }
+}
+```
+
+## Branching Workflow
+
+Neon branches are copy-on-write clones of your database -- instant, zero-cost until data diverges.
+
+```bash
+# List branches
+neonctl branches list --project-id <project-id>
+
+# Create feature branch from main
+neonctl branches create --project-id <project-id> \
+  --name feature/my-feature \
+  --parent main
+
+# Create branch with auto-expiration (CI/CD)
+neonctl branches create --project-id <project-id> \
+  --name ci-test-run-42 \
+  --parent main \
+  --expires-at "2026-04-01T00:00:00Z"
+
+# Reset branch to parent state
+neonctl branches reset feature/my-feature --parent --project-id <project-id>
+
+# Delete branch
+neonctl branches delete feature/my-feature --project-id <project-id>
+```
+
+### Branch Strategy
+
+| Branch | Purpose | Expiration |
+|--------|---------|------------|
+| `main` | Production database | Never |
+| `dev` | Development shared | Never |
+| `feature/*` | Feature development | 7 days |
+| `ci-*` | CI test runs | 1 day |
+
+## Scale-to-Zero
+
+Neon automatically suspends computes after inactivity (default: 5 minutes). This saves cost but introduces cold-start latency (~300-500ms on first request).
+
+### Mitigate Cold Starts
+
+```csharp
+// 1. Configure retry policy to handle connection drops on wake-up
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseNpgsql(connectionString, npgsqlOptions =>
+    {
+        npgsqlOptions.EnableRetryOnFailure(
+            maxRetryCount: 5,
+            maxRetryDelay: TimeSpan.FromSeconds(10),
+            errorCodesToAdd: null);
+    }));
+
+// 2. Health check to warm the connection pool
+builder.Services.AddHealthChecks()
+    .AddNpgSql(connectionString, name: "neon-db");
+```
+
+### Suspend Timeout Configuration
+
+```bash
+# Set suspend timeout to 10 minutes (600 seconds)
+neonctl branches create --project-id <project-id> \
+  --name main \
+  --suspend-timeout 600
+
+# Compute size range (autoscaling)
+neonctl branches create --project-id <project-id> \
+  --name main \
+  --cu "0.25-4"
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| Direct connection for app queries | Pooled (`-pooler`) connection | Direct connections exhaust compute limits |
+| No retry policy | `EnableRetryOnFailure()` | Cold starts drop first connection |
+| Hardcoded connection strings | Environment variables | Branches have unique endpoints |
+| Permanent CI branches | `--expires-at` TTL | Orphaned branches waste resources |
+| Running migrations on pooled connection | Direct connection for `dotnet ef` | PgBouncer doesn't support advisory locks |
+| No SSL | `SSL Mode=Require` | Neon requires encrypted connections |

package/framework/standards/integration/mcp/mcp-tools.md

@@ -19,8 +19,8 @@ await mcp__context7__resolve_library_id({ libraryName: "react" });
 // Playwright (browser automation)
 await mcp__playwright__browser_navigate({ url: "https://example.com" });
 
-// Supabase — use CLI, not MCP (always target local Docker instance)
-// npx supabase status → get DB URL
+// Neon — use `neonctl` CLI + `psql`
+// neonctl connection-string → get DB URL
 // psql <DB_URL> -c "SELECT ..."
 ```
 
@@ -85,39 +85,38 @@ const docs = await mcp__context7__query_docs({
 
 | Tool | Use Case | Example |
 |------|----------|---------|
-| **Supabase CLI / psql** | Database schema, tables, relationships, RLS (local Docker) | `psql <DB_URL> -c "SELECT ..."` |
+| **Neon CLI (`neonctl`) / psql** | Database schema, tables, relationships, RLS | `psql <DB_URL> -c "SELECT ..."` |
 | **Context7** | Library docs for architecture decisions | `mcp__context7__query_docs()` |
 | **GitHub** | Check existing code patterns, PRs | `mcp__github__search_code()` |
 
 ```bash
 # === SCHEMA ANALYSIS (Critical for contracts.cs) ===
-# Always target local Docker instance — never production.
 
-# 0. Get local DB URL (port may vary per instance)
-npx supabase status
-# → Extract "DB URL" line, e.g.: postgresql://postgres:postgres@127.0.0.1:54322/postgres
+# 0. Get Neon DB connection string
+neonctl connection-string
+# → e.g.: postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require
 
 # 1. List all tables
-npx supabase db dump --local --schema public 2>/dev/null | grep "CREATE TABLE"
+pg_dump $(neonctl connection-string) --schema-only --schema public 2>/dev/null | grep "CREATE TABLE"
 
 # 2. Get schema for each relevant table
-psql $DB_URL -c "SELECT column_name, data_type, is_nullable, column_default \
+psql $(neonctl connection-string) -c "SELECT column_name, data_type, is_nullable, column_default \
   FROM information_schema.columns WHERE table_name = 'leads' ORDER BY ordinal_position"
 
 # 3. Get foreign key relationships
-psql $DB_URL -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table, \
+psql $(neonctl connection-string) -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table, \
   ccu.column_name AS foreign_column FROM information_schema.table_constraints tc \
   JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name \
   JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name \
   WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'leads'"
 
 # 4. Check RLS policies (security-critical)
-psql $DB_URL -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
+psql $(neonctl connection-string) -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
 ```
 
-**Fallback (local Supabase not running):**
+**Fallback (Neon database not accessible):**
 ```
-1. Grep: "\.from\(|\.select\(|SELECT |supabase\.|DbSet<" → find query files
+1. Grep: "\.from\(|\.select\(|SELECT |DbSet<" → find query files
 2. Read each query file → extract table/column names
 3. Glob: "src/**/types/**/*.ts" or "**/Entities/**/*.cs" → find type definitions
 4. Read type files → map properties to database columns
@@ -167,7 +166,7 @@ for (const task of tasks) {
 
 | Tool | Use Case | Example |
 |------|----------|---------|
-| **Supabase CLI / psql** | Run migrations, create RLS policies (local Docker) | `npx supabase migration up --local` |
+| **Neon CLI (`neonctl`) / psql** | Run migrations, create RLS policies | `dotnet ef database update` |
 | **GitHub** | Create PR, push branches | `mcp__github__create_pull_request()` |
 | **Context7** | Look up API usage during coding | `mcp__context7__query_docs()` |
 | **Playwright** | Smoke test deployed features, verify UI | `mcp__playwright__browser_navigate()` |
@@ -176,20 +175,19 @@ for (const task of tasks) {
 | **Docker CLI** | Build, run, compose, logs (local) | `docker` commands |
 
 ```bash
-# === SUPABASE (Migrations & RLS — local Docker) ===
+# === NEON (Migrations & RLS via EF Core) ===
 
-# Create migration file
-npx supabase migration new add_status_to_leads
-# → Edit the generated SQL file in supabase/migrations/
+# Create migration
+dotnet ef migrations add AddStatusToLeads
 
-# Apply migration to local instance
-npx supabase migration up --local
+# Apply migration to Neon database
+dotnet ef database update
 
 # Verify schema after migration
-psql $DB_URL -c "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'leads'"
+psql $(neonctl connection-string) -c "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'leads'"
 
 # Verify RLS policies
-psql $DB_URL -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
+psql $(neonctl connection-string) -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
 ```
 
 ```javascript
@@ -238,7 +236,7 @@ await mcp__vercel__manage_env_vars({
 
 | Need | MCP Tool | Native Alternative |
 |------|----------|--------------------|
-| Database schema | Supabase CLI / psql (local Docker) | Grep queries + Read types |
+| Database schema | Neon CLI (`neonctl`) / psql | Grep queries + Read types |
 | Repo metadata | GitHub MCP | Bash `gh` CLI |
 | Library docs | Context7 | WebSearch + WebFetch |
 | Live page preview | Playwright MCP | WebFetch URL |
@@ -249,7 +247,7 @@ await mcp__vercel__manage_env_vars({
 | Cloud resources | Azure CLI (`az resource`, `az deployment`) | — |
 | Vercel deployments | Vercel MCP | Bash `vercel` CLI |
 
-**Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not. **Exceptions:** Supabase, Docker, and Azure always use their respective CLIs directly — never MCP.
+**Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not. **Exceptions:** Neon, Docker, and Azure always use their respective CLIs directly — never MCP.
 
 ---
 
@@ -345,26 +343,26 @@ await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/fil
 
 ---
 
-### Supabase: Full Schema Discovery (Local Docker via CLI)
+### Neon: Full Schema Discovery (via neonctl + psql)
 
-> **Primary:** Supabase CLI + psql targeting local Docker instance (`npx supabase start`).
-> **Port detection:** Always use `npx supabase status` to get the DB URL — port may vary across instances.
+> **Primary:** Neon CLI (`neonctl`) + psql connecting to Neon database.
+> **Connection:** Always use `neonctl connection-string` to get the DB URL.
 
 ```bash
 # Complete workflow for Phase 3 schema analysis
 
-# 1. Get local DB URL
-npx supabase status  # → extract "DB URL" line
+# 1. Get Neon DB URL
+neonctl connection-string  # → pooled connection string
 
 # 2. List all tables
-npx supabase db dump --local --schema public 2>/dev/null | grep "CREATE TABLE"
+pg_dump $(neonctl connection-string) --schema-only --schema public 2>/dev/null | grep "CREATE TABLE"
 
 # 3. For each relevant table:
-psql $DB_URL -c "SELECT column_name, data_type, is_nullable, column_default \
+psql $(neonctl connection-string) -c "SELECT column_name, data_type, is_nullable, column_default \
   FROM information_schema.columns WHERE table_name = 'TABLE_NAME' ORDER BY ordinal_position"
 
 # 4. Get relationships
-psql $DB_URL -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table \
+psql $(neonctl connection-string) -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table \
   FROM information_schema.table_constraints tc \
   JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name \
   JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name \
@@ -397,7 +395,7 @@ const docs = await mcp__context7__query_docs({
 ```javascript
 // Find patterns in large codebase during Phase 2
 const results = await mcp__github__search_code({
-  query: "supabase.from leads repo:myorg/myrepo",
+  query: "DbSet leads repo:myorg/myrepo",
 });
 // → Find all places that query the leads table
 ```
@@ -407,7 +405,7 @@ const results = await mcp__github__search_code({
 ## Security Considerations
 
 - **Never pass secrets** in MCP tool parameters (API keys, tokens, passwords)
-- **Supabase** uses CLI/psql targeting local Docker — never connect to production
+- **Neon** uses neonctl/psql — use database branches for development, not production
 - **GitHub MCP** inherits the configured token's permissions
 - **Always validate tool responses** before using in contracts or code generation