@polymorphism-tech/morph-spec 8.45.0 → 8.47.0

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

@@ -5,7 +5,7 @@
 > **Keywords:** coolify, docker, deploy, deployment, container, vps, ssh
 > **Load When:** coolify or docker deployment keywords detected
 
-**Verified against:** .NET 10 + Next.js 15 + Node 22 (Docker base images). Last-verified: 2026-07-07.
+**Verified against:** .NET 10 + Next.js 15 + Node 22 (Docker base images) + Coolify 4.x API. The `POST /api/v1/deploy` contract was checked against the Coolify docs/OpenAPI on 2026-10-03, and Coolify 4.3.23 was observed answering `GET /deploy` with "This endpoint has changed to a POST request"; Dockerfiles and snippets are documentary. Last-verified: 2026-10-03.
 
 ---
 
@@ -17,14 +17,14 @@ Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 
 Coolify is Polymorphism Tech's standard self-hosted deployment platform for Docker workloads.
 
-There is no MCP server or CLI tool for Coolify. All access is via **SSH into the VPS**, from which the Coolify API is reached at `http://localhost:8000/api/v1/` (it is not exposed publicly). The API token lives server-side only (e.g. `~/.coolify-token`, `chmod 600`) -- never print it, never commit it, never let it leave the SSH session.
+We do not use a Coolify MCP server or CLI. All access is via **SSH into the VPS**, from which the Coolify API is reached at `http://localhost:8000/api/v1/`: keep the VPS firewall to SSH and HTTP(S) only, so port 8000 never answers from outside. The API token lives server-side only (a `chmod 600` file in the SSH user's home, written here as `~/<token-file>`) -- read it inside the remote command, never print it, never commit it, never let it leave the SSH session.
 
 ```bash
 # Canonical access pattern — token is read and used entirely server-side
-ssh <vps-ssh-alias> 'T=$(cat ~/.coolify-token); curl -s -H "Authorization: Bearer $T" http://localhost:8000/api/v1/projects'
+ssh <vps-ssh-alias> 'T=$(cat ~/<token-file>); curl -s -H "Authorization: Bearer $T" http://localhost:8000/api/v1/projects'
 ```
 
-Useful endpoints: `/version`, `/projects`, `/servers`, `/applications`, `/deploy?uuid={uuid}`. Changing a domain: `PATCH /applications/{uuid}` with `{"domains":"https://x,https://www.x"}`, then `GET /deploy?uuid={uuid}` to redeploy.
+Useful endpoints: `GET /version`, `GET /projects`, `GET /servers`, `GET /applications`, `POST /deploy?uuid={uuid}`. Changing a domain: `PATCH /applications/{uuid}` with `{"domains":"https://x,https://www.x"}` (a `dockercompose` application refuses `domains` and takes `docker_compose_domains: [{"name":"<service>","domain":"https://x:<port>"}]`), then `POST /deploy?uuid={uuid}` to redeploy. The deploy trigger is **POST**: Coolify 4.3.23 answers a `GET /deploy` with "This endpoint has changed to a POST request" and deploys nothing, so a script that only greps for an error status reports a deploy that never happened.
 
 ## Core Rules
 
@@ -202,13 +202,15 @@ const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
 
 ## Triggering a Deploy via SSH + API
 
-Since there is no MCP server or CLI for Coolify, every deploy operation (manual redeploy, CI/CD, or troubleshooting) goes through the same SSH + curl pattern used for all other Coolify access:
+Every deploy operation (manual redeploy, CI/CD, or troubleshooting) goes through the same SSH + curl pattern used for all other Coolify access:
 
 ```bash
 # Redeploy an existing application after a new image/commit is ready
-ssh <vps-ssh-alias> 'T=$(cat ~/.coolify-token); curl -s -X GET -H "Authorization: Bearer $T" "http://localhost:8000/api/v1/deploy?uuid=<application-uuid>"'
+ssh <vps-ssh-alias> 'T=$(cat ~/<token-file>); curl -s -X POST -H "Authorization: Bearer $T" "http://localhost:8000/api/v1/deploy?uuid=<application-uuid>"'
 ```
 
+A queued deploy answers `{"deployments":[{"message":...,"resource_uuid":...,"deployment_uuid":...}]}`; treat a response without `deployment_uuid` as "nothing was deployed". `force=true` rebuilds without the build cache.
+
 In GitHub Actions this becomes an SSH step using a deploy key stored as a secret (see the `github-workflow-deploy-coolify` template) -- never a direct HTTP call to the Coolify API from the runner, since the API port is not reachable outside the VPS.
 
 ## Deployment Checklist

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

@@ -5,20 +5,22 @@
 > **Keywords:** pgvector, vector, embeddings, similarity search, HNSW, cosine
 > **Load When:** pgvector or embedding keywords detected
 
-**Verified against:** .NET 10 + Pgvector.EntityFrameworkCore + pgvector (HNSW). Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3 + Pgvector.EntityFrameworkCore 0.3.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08). The entity, configuration, DbContext, search-handler and raw-Npgsql blocks compile with `TreatWarningsAsErrors` (handler over the `Result`/`IHandler` of `result-pattern.md`/`vertical-slice.md`), and the handler's query shape was translated with `ToQueryString()` to `ORDER BY d.embedding <=> @query`; the SQL (index DDL, `ef_search`, the two SQL functions) is documentary, checked against the pgvector README. Last-verified: 2026-10-03.
 
 ---
 
-Stack: .NET VSA + Neon Serverless Postgres
+Stack: .NET VSA + Neon Serverless Postgres. For the end-to-end RAG pipeline (ingestion, retrieval, generation) on top of this mapping, see `backend/database/vector-search-rag.md`.
 
 ## 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
+- ALWAYS call `UseVector()` on the `UseNpgsql(...)` options builder (EF Core); `NpgsqlDataSourceBuilder.UseVector()` is only for raw Npgsql
+- ALWAYS register the `vector` extension in `OnModelCreating` (`HasPostgresExtension("vector")`)
+- Map vector properties as `Pgvector.Vector` -- EF Core does not map `float[]` or `ReadOnlyMemory<float>` to the `vector` column
+- Query through the `ApplicationDbContext` in the slice handler with the `CosineDistance`/`L2Distance`/`MaxInnerProduct` LINQ translations -- no repository class, no raw SQL from C# without a `decisions.md` justification
+- IDs come from the app (`Guid.CreateVersion7()`), never from a `gen_random_uuid()` column default
 
 ## Enable pgvector
 
@@ -26,54 +28,56 @@ Stack: .NET VSA + Neon Serverless Postgres
 CREATE EXTENSION IF NOT EXISTS vector;
 ```
 
+`HasPostgresExtension("vector")` in `OnModelCreating` makes the EF Core migration emit this statement, so a hand-written migration is not needed.
+
 ## EF Core Entity Mapping
 
-### NuGet Package
+### NuGet Packages
 
-```bash
-dotnet add package Pgvector.EntityFrameworkCore
+```xml
+<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.3" />
+<PackageReference Include="Pgvector.EntityFrameworkCore" Version="0.3.0" />
 ```
 
+`Pgvector.EntityFrameworkCore` 0.3.0 requires `Npgsql.EntityFrameworkCore.PostgreSQL` >= 9.0.1 and brings `Pgvector` (the `Vector` type and the raw-Npgsql plugin) transitively. The configuration below maps each column to the snake_case names of `backend/database/postgresql/database.md` (`embedding`, `created_at`) with `HasColumnName`; without it EF creates `"Embedding"`, `"CreatedAt"` and every SQL snippet below would have to quote PascalCase names. (A project that wants this for every entity can add `EFCore.NamingConventions` and `UseSnakeCaseNamingConvention()` once, instead of per column -- a project-wide decision for `decisions.md`.)
+
 ### Entity Definition
 
 ```csharp
-using System.ComponentModel.DataAnnotations.Schema;
 using Pgvector;
 
-public class Document
+public sealed 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;
+    public DateTimeOffset CreatedAt { get; set; }
 }
 ```
 
+`Id` and `CreatedAt` are set by the handler that creates the row (`Guid.CreateVersion7()` and `TimeProvider.GetUtcNow()`), not by property initializers or column defaults. `Embedding` is nullable because a row can exist before its embedding is generated.
+
 ### IEntityTypeConfiguration
 
 ```csharp
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
 
-public class DocumentConfiguration : IEntityTypeConfiguration<Document>
+public sealed 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.Property(d => d.Id).HasColumnName("id").ValueGeneratedNever();
+        builder.Property(d => d.Title).HasColumnName("title").IsRequired();
+        builder.Property(d => d.Content).HasColumnName("content").IsRequired();
+        builder.Property(d => d.Metadata).HasColumnName("metadata").HasColumnType("jsonb");
+        builder.Property(d => d.Embedding).HasColumnName("embedding").HasColumnType("vector(1536)");
+        builder.Property(d => d.CreatedAt).HasColumnName("created_at");
+
         builder.HasIndex(d => d.Embedding)
             .HasMethod("hnsw")
             .HasOperators("vector_cosine_ops")
@@ -86,12 +90,12 @@ public class DocumentConfiguration : IEntityTypeConfiguration<Document>
 ### DbContext Setup
 
 ```csharp
-public class AppDbContext : DbContext
+using Microsoft.EntityFrameworkCore;
+
+public sealed class ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : DbContext(options)
 {
     public DbSet<Document> Documents => Set<Document>();
 
-    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
-
     protected override void OnModelCreating(ModelBuilder modelBuilder)
     {
         modelBuilder.HasPostgresExtension("vector");
@@ -99,13 +103,22 @@ public class AppDbContext : DbContext
     }
 }
 
-// Registration with vector support
-builder.Services.AddDbContext<AppDbContext>(options =>
-    options.UseNpgsql(connectionString, npgsql => npgsql.UseVector()));
+public static class VectorDatabaseRegistration
+{
+    public static IServiceCollection AddVectorDatabase(this IServiceCollection services, IConfiguration configuration) =>
+        services.AddDbContext<ApplicationDbContext>(options =>
+            options.UseNpgsql(
+                    configuration.GetConnectionString("DefaultConnection"),
+                    npgsql => npgsql.UseVector()));
+}
 ```
 
+The connection string comes from configuration (user-secrets in development, environment variables in Coolify) -- see `infrastructure/neon/neon-setup.md`.
+
 ## HNSW Index Creation (Raw SQL)
 
+The EF configuration above generates the cosine index. The SQL equivalents, for reference and for hand-written migrations:
+
 ```sql
 -- Cosine distance (most common for normalized embeddings)
 CREATE INDEX idx_documents_embedding ON documents
@@ -115,10 +128,15 @@ CREATE INDEX idx_documents_embedding ON documents
 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;
+-- Tune search accuracy for the current transaction
+BEGIN;
+SET LOCAL hnsw.ef_search = 100;
+-- ... similarity query ...
+COMMIT;
 ```
 
+On the Neon pooled (`-pooler`, PgBouncer transaction mode) endpoint a plain `SET` does not stick to your next statement: use `SET LOCAL` inside the same transaction as the query, or set it per role/database.
+
 ### HNSW Parameters
 
 | Parameter | Default | Tuning |
@@ -129,15 +147,58 @@ SET hnsw.ef_search = 100;
 
 ## 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 |
+| Operator | LINQ (Pgvector.EntityFrameworkCore) | Index Ops | Use Case |
+|----------|-------------------------------------|-----------|----------|
+| `<=>` | `CosineDistance` | `vector_cosine_ops` | Normalized embeddings (most common) |
+| `<->` | `L2Distance` | `vector_l2_ops` | Spatial/positional data |
+| `<#>` | `MaxInnerProduct` (negative inner product) | `vector_ip_ops` | Pre-normalized, max similarity |
+
+The index operator class must match the function used in the query, or Postgres ignores the index and falls back to a sequential scan.
 
 ## Similarity Search
 
-### SQL Function
+### Search handler (EF Core in the slice)
+
+```csharp
+// Features/DocumentFeature/SearchDocuments/SearchDocumentsHandler.cs
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.AI;
+using Pgvector;
+using Pgvector.EntityFrameworkCore;
+
+public sealed record SearchDocumentsRequest(string Query, int Limit = 10, double MinSimilarity = 0.78);
+public sealed record DocumentMatch(Guid Id, string Title, string Content, double Similarity);
+
+public sealed class SearchDocumentsHandler(
+    ApplicationDbContext db,
+    IEmbeddingGenerator<string, Embedding<float>> embeddings)
+    : IHandler<SearchDocumentsRequest, Result<IReadOnlyList<DocumentMatch>>>
+{
+    public async Task<Result<IReadOnlyList<DocumentMatch>>> HandleAsync(
+        SearchDocumentsRequest request, CancellationToken cancellationToken)
+    {
+        var query = new Vector(await embeddings.GenerateVectorAsync(request.Query, cancellationToken: cancellationToken));
+        var maxDistance = 1 - request.MinSimilarity;
+
+        var matches = await db.Documents
+            .Where(d => d.Embedding != null)
+            .Select(d => new { d.Id, d.Title, d.Content, Distance = d.Embedding!.CosineDistance(query) })
+            .Where(x => x.Distance <= maxDistance)
+            .OrderBy(x => x.Distance)
+            .Take(request.Limit)
+            .Select(x => new DocumentMatch(x.Id, x.Title, x.Content, 1 - x.Distance))
+            .ToListAsync(cancellationToken);
+
+        return Result.Success<IReadOnlyList<DocumentMatch>>(matches);
+    }
+}
+```
+
+Storing an embedding is an ordinary EF write in the handler that owns the document: `document.Embedding = new Vector(await embeddings.GenerateVectorAsync(text, cancellationToken: ct));` followed by `SaveChangesAsync`. No `UPDATE ... SET embedding` from C#.
+
+### SQL Functions (only with a `decisions.md` justification)
+
+When the query must live in the database (called from several apps, or a hybrid score the LINQ translation cannot express), a SQL function is acceptable -- record why in `decisions.md`, call it through EF Core with interpolated parameters, and keep the same distance rules:
 
 ```sql
 CREATE OR REPLACE FUNCTION match_documents(
@@ -155,40 +216,10 @@ LANGUAGE sql STABLE AS $$
 $$;
 ```
 
-### 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)
 
+Blends the vector score with `ts_rank`. Same rule as above: a SQL function, justified in `decisions.md`.
+
 ```sql
 CREATE OR REPLACE FUNCTION hybrid_search(
   query_text text,
@@ -218,14 +249,25 @@ LANGUAGE sql STABLE AS $$
 $$;
 ```
 
+For Portuguese content use the `'portuguese'` text search configuration in both `to_tsvector` and `plainto_tsquery`.
+
 ## Npgsql Vector Type Handler
 
-The `Pgvector.EntityFrameworkCore` package automatically registers the vector type handler when you call `UseVector()`. For raw Npgsql (without EF Core):
+With EF Core, `npgsql.UseVector()` inside `UseNpgsql(...)` registers the type mapping and the LINQ translations. For raw Npgsql (without EF Core), register the plugin on the data source:
 
 ```csharp
-var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
-dataSourceBuilder.UseVector();
-await using var dataSource = dataSourceBuilder.Build();
+using Npgsql;
+using Pgvector.Npgsql;
+
+public static class RawVectorDataSource
+{
+    public static NpgsqlDataSource Build(string connectionString)
+    {
+        var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
+        dataSourceBuilder.UseVector();
+        return dataSourceBuilder.Build();
+    }
+}
 ```
 
 ## Common Mistakes
@@ -234,7 +276,10 @@ await using var dataSource = dataSourceBuilder.Build();
 |-------|-------|-----|
 | 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 |
+| Missing `UseVector()` | `npgsql.UseVector()` in `UseNpgsql(...)` | 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 |
+| `float[]` / `ReadOnlyMemory<float>` for the EF property | `Vector` from the Pgvector package | EF Core mapping requires the Pgvector type |
 | No `HasPostgresExtension("vector")` | Add in `OnModelCreating` | Extension must be declared for migrations |
+| A `DocumentRepository` with `ExecuteSqlInterpolatedAsync`/`SqlQuery` | LINQ `CosineDistance` in the slice handler | `DbSet<T>` is already the repository; raw SQL bypasses the translation that keeps the index in use |
+| `SET hnsw.ef_search` on the pooled endpoint | `SET LOCAL` inside the query's transaction | PgBouncer transaction mode hands the next statement another server session |
+| `HasDefaultValueSql("gen_random_uuid()")` on the id | `Id = Guid.CreateVersion7()` in the handler | App-generated, time-ordered ids |

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

@@ -1,11 +1,11 @@
 # Neon Serverless Postgres Standard
 
 > **Scope:** neon
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `neon-standards` em `**/neon/**`, `**/database/**` e migrations `.sql`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** neon, serverless postgres, branching, scale-to-zero, connection string, neonctl
 > **Load When:** neon stack detected
 
-**Verified against:** .NET 10 + Npgsql/EF Core 10 + neonctl. Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3 + neonctl. The DbContext registration, design-time factory and cold-start blocks compile with `TreatWarningsAsErrors`; that Npgsql 10 rejects `postgresql://` URIs and marks `Trust Server Certificate` as "no longer needed and does nothing" was measured on 10.0.3; the suspend-timeout API and `--cu` ranges were checked against the Neon docs (context7). neonctl commands are documentary. Last-verified: 2026-10-03.
 
 ---
 
@@ -15,7 +15,7 @@ Stack: .NET + Neon Serverless Postgres
 
 - 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
+- NEVER hardcode connection strings or commit them in `appsettings*.json` -- user-secrets in development, environment variables in Coolify
 - 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
@@ -42,38 +42,49 @@ neonctl projects list
 | 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
+### Configuration Keys
 
-| Variable | Purpose |
-|----------|---------|
-| `DATABASE_URL` | Pooled connection for application runtime |
-| `DATABASE_URL_UNPOOLED` | Direct connection for migrations and CLI tools |
+The .NET app reads two connection strings through `IConfiguration`. Neon's integrations call them `DATABASE_URL` / `DATABASE_URL_UNPOOLED`; in .NET they are:
 
-```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"
+| .NET key (env var form) | Neon name | Purpose |
+|-------------------------|-----------|---------|
+| `ConnectionStrings:DefaultConnection` (`ConnectionStrings__DefaultConnection`) | `DATABASE_URL` | Pooled connection for application runtime |
+| `ConnectionStrings:MigrationConnection` (`ConnectionStrings__MigrationConnection`) | `DATABASE_URL_UNPOOLED` | Direct connection for migrations and CLI tools |
 
-# 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"
+Npgsql only parses the **keyword** format (`Host=...;Database=...`). The `postgresql://user:pass@host/db?sslmode=require` URI that the Neon console shows by default throws `ArgumentException` in `NpgsqlConnectionStringBuilder` (measured on Npgsql 10.0.3): copy the .NET form from the console's connection dialog, or convert it.
+
+```bash
+# Development: user-secrets (stored outside the repo, per user)
+dotnet user-secrets init
+dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Host=<endpoint-id>-pooler.<region>.aws.neon.tech;Database=<db>;Username=<role>;Password=<password>;SSL Mode=Require"
+dotnet user-secrets set "ConnectionStrings:MigrationConnection" "Host=<endpoint-id>.<region>.aws.neon.tech;Database=<db>;Username=<role>;Password=<password>;SSL Mode=Require"
+
+# Production (Coolify environment variables, set in the UI or API -- never in the Dockerfile)
+# ConnectionStrings__DefaultConnection=Host=<endpoint-id>-pooler.<region>.aws.neon.tech;...;SSL Mode=Require
+# ConnectionStrings__MigrationConnection=Host=<endpoint-id>.<region>.aws.neon.tech;...;SSL Mode=Require
 ```
 
 ## EF Core Configuration
 
 ### appsettings.json
 
+`appsettings.json` is committed, so it carries **no** connection string with a password -- the keys come from user-secrets / environment variables, which override it:
+
 ```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"
+    "DefaultConnection": "",
+    "MigrationConnection": ""
   }
 }
 ```
 
+Drop `Trust Server Certificate=true` from older samples (including Neon's own): since Npgsql 6 it is obsolete, and on Npgsql 10 the builder's attribute reads "no longer needed and does nothing". `SSL Mode=Require` encrypts; `SSL Mode=VerifyFull` also validates the certificate chain and host name.
+
 ### DbContext Registration
 
 ```csharp
-builder.Services.AddDbContext<AppDbContext>(options =>
+builder.Services.AddDbContext<ApplicationDbContext>(options =>
     options.UseNpgsql(
         builder.Configuration.GetConnectionString("DefaultConnection"),
         npgsqlOptions =>
@@ -89,24 +100,30 @@ builder.Services.AddDbContext<AppDbContext>(options =>
 ### Design-Time Factory (for migrations using direct connection)
 
 ```csharp
-public class AppDbContextFactory : IDesignTimeDbContextFactory<AppDbContext>
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Design;
+
+public sealed class ApplicationDbContextFactory : IDesignTimeDbContextFactory<ApplicationDbContext>
 {
-    public AppDbContext CreateDbContext(string[] args)
+    public ApplicationDbContext CreateDbContext(string[] args)
     {
         var configuration = new ConfigurationBuilder()
             .AddJsonFile("appsettings.json")
+            .AddUserSecrets<ApplicationDbContextFactory>(optional: true)
             .AddEnvironmentVariables()
             .Build();
 
-        var optionsBuilder = new DbContextOptionsBuilder<AppDbContext>();
+        var optionsBuilder = new DbContextOptionsBuilder<ApplicationDbContext>();
         optionsBuilder.UseNpgsql(
             configuration.GetConnectionString("MigrationConnection"));
 
-        return new AppDbContext(optionsBuilder.Options);
+        return new ApplicationDbContext(optionsBuilder.Options);
     }
 }
 ```
 
+`AddUserSecrets` reads the same secrets the app uses in development, and `AddEnvironmentVariables` (last, so it wins) lets CI pass `ConnectionStrings__MigrationConnection`.
+
 ## Branching Workflow
 
 Neon branches are copy-on-write clones of your database -- instant, zero-cost until data diverges.
@@ -149,8 +166,10 @@ Neon automatically suspends computes after inactivity (default: 5 minutes). This
 ### Mitigate Cold Starts
 
 ```csharp
+var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
+
 // 1. Configure retry policy to handle connection drops on wake-up
-builder.Services.AddDbContext<AppDbContext>(options =>
+builder.Services.AddDbContext<ApplicationDbContext>(options =>
     options.UseNpgsql(connectionString, npgsqlOptions =>
     {
         npgsqlOptions.EnableRetryOnFailure(
@@ -159,32 +178,35 @@ builder.Services.AddDbContext<AppDbContext>(options =>
             errorCodesToAdd: null);
     }));
 
-// 2. Health check to warm the connection pool
+// 2. Health check to warm the connection pool (package AspNetCore.HealthChecks.NpgSql)
 builder.Services.AddHealthChecks()
-    .AddNpgSql(connectionString, name: "neon-db");
+    .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
+Set it when the branch (and its compute) is created; `main` already exists, so it is never recreated to change a setting:
 
-# Compute size range (autoscaling)
+```bash
+# New branch with a 10-minute suspend timeout and an autoscaling range
 neonctl branches create --project-id <project-id> \
-  --name main \
+  --name feature/my-feature \
+  --parent main \
+  --suspend-timeout 600 \
   --cu "0.25-4"
 ```
 
+For an **existing** compute (e.g. `main`'s), change `suspend_timeout_seconds` in the Console or with the API (`PATCH /projects/{project-id}/endpoints/{endpoint-id}` with `{"endpoint":{"suspend_timeout_seconds":600}}`; default 300, min 60, max 604800), with the Neon API key read from the environment, never typed into the command.
+
 ## 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 |
+| Hardcoded / committed connection strings | user-secrets (dev), env vars (Coolify) | Branches have unique endpoints, and a committed password leaks |
+| `postgresql://` URI in `ConnectionStrings` | Keyword format (`Host=...;SSL Mode=Require`) | Npgsql does not parse URIs |
+| `Trust Server Certificate=true` | Drop it (`SSL Mode=Require` or `VerifyFull`) | Obsolete; does nothing on Npgsql 10 |
 | 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/templates/code/dotnet/contracts/contracts-vsa.cs

@@ -183,10 +183,10 @@ internal sealed class Create{{pascalCase FEATURE_NAME}}Endpoint : IApiEndpoint
             var result = await handler.HandleAsync(command, cancellationToken);
             return result.Match(
                 onSuccess: () => Results.Ok(result.Value),
-                onFailure: error => Results.BadRequest(error));
+                onFailure: error => error.ToHttpResult());
         })
         .WithTags("{{pascalCase FEATURE_NAME}}s")
         .Produces<Create{{pascalCase FEATURE_NAME}}Response>(StatusCodes.Status200OK)
-        .Produces(StatusCodes.Status400BadRequest);
+        .ProducesProblem(StatusCodes.Status400BadRequest);
     }
 }

package/framework/templates/code/dotnet/extensions/database-extensions.cs

@@ -11,7 +11,7 @@ namespace {{pascalCase PROJECT_NAME}}.Extensions
 
             services.AddDbContext<ApplicationDbContext>(options =>
             {
-                options.UseNpgsql(configuration.GetConnectionString("connection"));
+                options.UseNpgsql(configuration.GetConnectionString("DefaultConnection"));
             });
 
             return services;

package/framework/templates/code/dotnet/extensions/result-extensions.cs

@@ -25,3 +25,30 @@ public static class ResultExtensions
             : onFailure(result.Error);
     }
 }
+
+public static class ErrorHttpMapping
+{
+    public static int StatusCodeFor(ErrorType type) => type switch
+    {
+        ErrorType.Validation => StatusCodes.Status400BadRequest,
+        ErrorType.NotFound => StatusCodes.Status404NotFound,
+        ErrorType.Conflict => StatusCodes.Status409Conflict,
+        ErrorType.Unauthorized => StatusCodes.Status401Unauthorized,
+        ErrorType.Forbidden => StatusCodes.Status403Forbidden,
+        ErrorType.Unexpected => StatusCodes.Status500InternalServerError,
+        _ => StatusCodes.Status400BadRequest
+    };
+
+    public static IResult ToHttpResult(this Error error)
+    {
+        Dictionary<string, object?>? extensions = error is ValidationError validation
+            ? new() { ["errors"] = validation.Errors.Select(e => new { e.Code, e.Description }).ToArray() }
+            : null;
+
+        return Results.Problem(
+            title: error.Code,
+            detail: error.Description,
+            statusCode: StatusCodeFor(error.Type),
+            extensions: extensions);
+    }
+}

package/framework/templates/code/dotnet/feature/endpoint.cs.hbs

@@ -12,10 +12,10 @@ internal sealed class {{pascalCase SLICE_NAME}}Endpoint : IApiEndpoint
             var result = await handler.HandleAsync(command, cancellationToken);
             return result.Match(
               onSuccess: () => Results.Ok(result.Value),
-              onFailure: error => Results.BadRequest(error));
+              onFailure: error => error.ToHttpResult());
         })
         .WithTags(ApiTags.{{pascalCase FEATURE_NAME}}s)
         .Produces<{{pascalCase SLICE_NAME}}Response>(StatusCodes.Status200OK)
-        .Produces(StatusCodes.Status400BadRequest);
+        .ProducesProblem(StatusCodes.Status400BadRequest);
     }
 }

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/MediaDisclosureTests.cs

@@ -49,7 +49,7 @@ public sealed class MediaDisclosureTests
         Assert.False(
             result.IsSuccess,
             "publicar sem marcacao e o caminho que a obrigacao legal existe para fechar; " +
-            "se ele existe, a afirmacao da rubrica media-claims esta presa so por prosa");
+            "se ele existe, a prova de midia do Gate 3 esta presa so por prosa");
         Assert.Equal(MediaErrorCode.InvalidTransition, result.Error!.Code);
         Assert.Contains("marcacao", result.Error.Message, StringComparison.OrdinalIgnoreCase);
     }

package/framework/templates/infrastructure/docker/coolify.template.json

@@ -3,10 +3,10 @@
   "provider": "coolify",
   "access": {
     "method": "ssh",
-    "note": "No MCP/CLI exists for Coolify — replace sshHost with the real SSH alias for the target VPS. The API is reached only from inside the VPS, at apiBaseUrl.",
+    "note": "We use no Coolify MCP/CLI — replace sshHost with the real SSH alias for the target VPS and tokenPath with the chmod-600 token file in that user's home. The API is reached only from inside the VPS, at apiBaseUrl; the deploy trigger is POST /deploy?uuid= (GET is refused by Coolify 4.3.23).",
     "sshHost": "REPLACE_WITH_VPS_SSH_ALIAS",
     "apiBaseUrl": "http://localhost:8000/api/v1",
-    "tokenPath": "~/.coolify-token"
+    "tokenPath": "~/REPLACE_WITH_TOKEN_FILE"
   },
   "application": {
     "uuid": "REPLACE_WITH_COOLIFY_APPLICATION_UUID",
@@ -45,5 +45,5 @@
       "https": true
     }
   ],
-  "deployCommand": "ssh REPLACE_WITH_VPS_SSH_ALIAS 'T=$(cat ~/.coolify-token); curl -s -X GET -H \"Authorization: Bearer $T\" \"http://localhost:8000/api/v1/deploy?uuid=REPLACE_WITH_COOLIFY_APPLICATION_UUID\"'"
+  "deployCommand": "ssh REPLACE_WITH_VPS_SSH_ALIAS 'T=$(cat ~/REPLACE_WITH_TOKEN_FILE); curl -s -X POST -H \"Authorization: Bearer $T\" \"http://localhost:8000/api/v1/deploy?uuid=REPLACE_WITH_COOLIFY_APPLICATION_UUID\"'"
 }