@polymorphism-tech/morph-spec 8.46.0 → 9.0.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/standards/integration/mcp/mcp-tools.md

@@ -195,14 +195,14 @@ Fallback: WebSearch for library capabilities.
 
 | Tool | Use Case | Example |
 |------|----------|---------|
-| **GitHub CLI (`gh`)** | Create issues from tasks, link to milestone | `gh issue create` (Bash) |
+| **GitHub CLI (`gh`)** | Create issues from slices, link to milestone | `gh issue create` (Bash) |
 | **Context7** | Estimate complexity based on library docs | `mcp__context7__query-docs()` |
 
 ```bash
-# Create GitHub issues from tasks.json (if team uses GitHub Projects)
-# — one `gh issue create` per task, iterating tasks.json:
-gh issue create --title "T001: Create Entity Lead" \
-  --body "description + doneCriteria da task" \
+# Create GitHub issues from the plan's slices (if team uses GitHub Projects)
+# — one `gh issue create` per slice of .morph/features/{f}/2-plan/checks.json:
+gh issue create --title "F1: Create Entity Lead" \
+  --body "fatia F1 do plan.md + cenários que ela cobre" \
   --label "backend" --milestone "feature-x"
 ```
 
@@ -234,7 +234,7 @@ psql $(neonctl connection-string) -c "SELECT column_name, data_type FROM informa
 psql $(neonctl connection-string) -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
 ```
 
-Look up the API while coding, then smoke test the deployed feature: the snapshot shows whether the page renders, the console messages catch JavaScript errors and failed API calls, and the screenshot goes to `recap.md`. Vercel covers deployment status, logs and environment variables.
+Look up the API while coding, then smoke test the deployed feature: the snapshot shows whether the page renders, the console messages catch JavaScript errors and failed API calls, and the screenshot goes to the slice report (`3-implement/reports/F{n}.md`). Vercel covers deployment status, logs and environment variables.
 
 ```javascript
 const docs = await mcp__context7__query-docs({
@@ -329,7 +329,7 @@ await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/fil
 | Implement (7) | Smoke test deployed features | `browser_navigate` + `browser_click` + `browser_snapshot` |
 | Implement (7) | Verify form flows end-to-end | `browser_fill_form` + `browser_click` + `browser_snapshot` |
 | Implement (7) | Check console errors after deploy | `browser_navigate` + `browser_console_messages` |
-| Implement (7) | Screenshot for recap.md | `browser_take_screenshot` |
+| Implement (7) | Screenshot for the slice report | `browser_take_screenshot` |
 
 ---
 

package/framework/templates/README.md

@@ -18,8 +18,7 @@ through the registry, and this README never repeats a path the registry already
 
 ```
 framework/templates/
-├── docs/              # Phase documents (proposal, spec, ui-*)
-├── feature/           # decisions.md, recap.md
+├── docs/              # plan.md (the plan's single source) and ui-mockups.md
 ├── context/           # ARCHITECTURE.md, design-system.md
 │
 ├── code/              # Code templates, by technology
@@ -38,7 +37,7 @@ framework/templates/
 ├── integrations/      # asaas-client, asaas-webhook, neon-auth-config
 ├── ui/                # design-system.css
 ├── meta-prompts/      # fusion, squad-leaders, validators
-├── examples/          # spec-examples.md, design-system-examples.md
+├── examples/          # design-system-examples.md
 └── REGISTRY.json      # template metadata — the index every consumer reads
 ```