@polymorphism-tech/morph-spec 10.0.0 → 10.2.0

package/framework/standards/architecture/stack-baseline.md

@@ -2,10 +2,10 @@
 
 > **Scope:** universal
 > **Layer:** 0 (lido pela `morph-plan` quando o projeto ainda não declara `project.stack`, e pelo `init` num diretório vazio)
-> **Keywords:** stack, greenfield, projeto novo, .NET, VSA, EF Core, Neon, Next.js, Shadcn, MAF, Hangfire
-> **Load When:** escolhendo a stack de um projeto novo, ou julgando um desvio de stack no plano
+> **Keywords:** stack, greenfield, projeto novo, .NET, VSA, EF Core, Neon, Next.js, Shadcn, MAF, Hangfire, postgres first, fila, grafo, jsonb, serviço de dados
+> **Load When:** escolhendo a stack de um projeto novo, julgando um desvio de stack no plano, ou diante de um serviço de dados novo (cache, fila, vetor, busca, grafo, banco de documento)
 
-**Verified against:** .NET 10, EF Core 10, Next.js 16 App Router, Microsoft Agent Framework 1.0. Last-verified: 2026-10-27.
+**Verified against:** .NET 10, EF Core 10, Next.js 16 App Router, Microsoft Agent Framework 1.0; catálogo de extensões do Neon lido em 2026-10-30. Last-verified: 2026-10-30.
 
 ---
 
@@ -25,6 +25,29 @@ Projeto novo começa nela **inteira** (`dotnet+nextjs --with neon`), mesmo quand
 
 Recortes, quando o usuário os escolhe: só API (`dotnet`), só site ou app web (`nextjs`).
 
+## Postgres primeiro
+
+Necessidade nova de dado começa no Postgres que o projeto já tem. Serviço a menos é menos rede, menos operação e um lugar só para depurar. Sair dele é decisão medida, registrada como ADR que diz por que o Postgres não cobre: nunca antecipação de um problema que ainda não existe.
+
+| Necessidade | No Postgres | Sai quando |
+| --- | --- | --- |
+| Dado flexível, documento | Coluna tipada; `jsonb` só no que varia (`backend-database-postgresql-database#jsonb`) | Quase nunca: banco de documento pede ADR (`data-nosql-cosmos-db`) |
+| RAG, busca semântica | pgvector + HNSW (`ai-agents-rag-custom-pgvector`) | O corpus estoura o HNSW: `lakebase_vector`, com ADR |
+| Busca por termo, híbrida | `tsvector` + GIN + RRF (`infrastructure-neon-pgvector#hybrid-search-vector--full-text`) | Eval mostra ranking ruim: `lakebase_text`, com ADR |
+| Job, fila | Hangfire ou claim com `SKIP LOCKED` (`backend-dotnet-vsa-handler-patterns#queue-on-postgres`) | Vazão medida acima do que o banco aguenta, ou consumidores fora da app |
+| Grafo, hierarquia | Chave estrangeira, CTE recursiva, `ltree` | Travessia profunda é o produto, e a medida mostra a CTE no limite |
+| Cache | Nenhum: índice e consulta primeiro | Latência medida que o índice não resolve: `data-nosql-cache-redis` |
+
+Arquivo, gateway de LLM, ambiente descartável e diagnóstico de consulta o próprio Neon entrega: confira `infrastructure-neon-platform` antes de contratar serviço.
+
+Grafo e ontologia não são requisito de RAG: dado bem modelado, com metadados no chunk, recupera bem. Testar é barato; adotar sem eval, não.
+
+**Fora do catálogo do Neon** (verificado em 2026-10-30): `pg_search` foi removido e `pgrag` está deprecado; `pgmq` e Apache AGE não estão na lista de extensões, então `CREATE EXTENSION` falha. O `pgmq` tem instalação só-SQL, não testada aqui, e o claim com `SKIP LOCKED` já o dispensa. Tutorial que manda subir um deles vale para Postgres próprio ou Supabase; usar na nossa stack exige ADR de hospedagem.
+
+**Custo que o Neon cobra:** worker que faz polling mantém o compute acordado e anula o scale to zero. Fila no banco é barata em serviço, não em compute.
+
+**Escala:** a OpenAI serve 800 milhões de usuários com um primário e quase 50 réplicas de leitura, mas mandou write-heavy novo para sistemas shardados (Cosmos DB); a RudderStack chegou a 100 mil eventos/s com fila em Postgres particionada em tabelas descartadas por `DROP`. Postgres não é para sempre: é o ponto de partida que aguenta até uma medida dizer o contrário.
+
 ## Declarar
 
 `morph-spec stack-set dotnet+nextjs --with neon` (mais `maf` quando houver agentes) grava a stack no `config.json` e

package/framework/standards/backend/database/postgresql/database.md

@@ -5,7 +5,7 @@
 > **Keywords:** postgresql, postgres, sql, neon, database schema
 > **Load When:** neon or postgresql keywords detected
 
-**Verified against:** PostgreSQL 16/17 + EF Core 10.0.12 (Npgsql provider 10.0.3) + @neondatabase/serverless. The EF Core query blocks compile with `TreatWarningsAsErrors` inside a wrapper method over stand-in entities; the SQL is documentary. Last-verified: 2026-10-03.
+**Verified against:** PostgreSQL 16/17 + EF Core 10.0.12 (Npgsql provider 10.0.3) + @neondatabase/serverless. The EF Core query blocks compile with `TreatWarningsAsErrors` inside a wrapper method over stand-in entities; the SQL is documentary. Last-verified: 2026-10-30.
 
 ---
 
@@ -221,6 +221,27 @@ create index idx_posts_content_search
 
 ---
 
+## JSONB
+
+Model first. A column with a type and a constraint is what lets you trust the data a year from now; a
+bag of JSON with no owner ends in a migration that takes months and loses what nobody can interpret.
+
+- **`jsonb` holds only what truly varies per row**: document metadata, a provider payload kept for
+  audit, a rendered spec. Never the whole entity "because we don't know the shape yet".
+- **What you filter, join, sort or aggregate is a column.** A field that started in `jsonb` and became
+  a query gets promoted, in a migration.
+- **The app validates the shape on write.** `jsonb` checks that it is JSON, nothing else.
+- **Index the query you have:** `USING gin (metadata jsonb_path_ops)` for containment (`@>`), or a
+  btree expression index on one key.
+
+```sql
+create index idx_documents_metadata on public.documents using gin (metadata jsonb_path_ops);
+
+select id from public.documents where metadata @> '{"source": "manual"}';
+```
+
+---
+
 ## Functions & Triggers
 
 ### Auto-update Timestamp

package/framework/standards/backend/dotnet/vsa-handler-patterns.md

@@ -5,7 +5,7 @@
 > **Keywords:** vsa, handler, feature-slice, vertical-slice, minimal-api, endpoint
 > **Load When:** dotnet VSA projects
 
-**Verified against:** .NET 10 (SDK 10.0.400-preview; minimal APIs, primary constructors, `Guid.CreateVersion7()`). The "Complete Endpoint Example" block compiles with `TreatWarningsAsErrors` over the `Result`/`ErrorHttpMapping` of `result-pattern.md` (in `ProjectName.Abstractions`/`ProjectName.Extensions`, reached only through the block's own `using`s); the other blocks are documentary. Last-verified: 2026-10-03.
+**Verified against:** .NET 10 (SDK 10.0.400-preview; minimal APIs, primary constructors, `Guid.CreateVersion7()`). The "Complete Endpoint Example" block compiles with `TreatWarningsAsErrors` over the `Result`/`ErrorHttpMapping` of `result-pattern.md` (in `ProjectName.Abstractions`/`ProjectName.Extensions`, reached only through the block's own `using`s); the other blocks are documentary. The "Queue on Postgres" claim ran sequentially on PGlite 0.5.13 (PostgreSQL 18): the eligibility predicate and the lease hold, while lock contention needs the integration test the section requires. Last-verified: 2026-10-30.
 
 ---
 
@@ -230,6 +230,38 @@ specific SQL → dedicated hand-written store + `plan.md` (`## Decisões`) entry
 (`FromSqlRaw`) unless a query genuinely cannot be expressed in LINQ — and document that
 in `plan.md` (`## Decisões`).
 
+### Queue on Postgres
+
+Fire-and-forget and scheduled work go through Hangfire (`backend-integrations-hangfire-hangfire-jobs`).
+A domain queue, whose jobs have state the app reads (progress, attempts, a screen), is a table with a
+claim in a dedicated store. `FOR UPDATE SKIP LOCKED` picks one eligible row and marks it in the same
+statement, so two workers never take the same job:
+
+```sql
+UPDATE jobs
+   SET status = 'processing', attempts = attempts + 1, lease_until = now() + interval '2 minutes'
+ WHERE id = (
+   SELECT id FROM jobs
+    WHERE status = 'pending'
+       OR (status = 'processing' AND lease_until <= now() AND attempts < 3)
+    ORDER BY created_at
+    FOR UPDATE SKIP LOCKED
+    LIMIT 1
+ )
+RETURNING id, attempts;
+```
+
+- **The lease is renewed** while the job runs: a fixed lease expires in the middle of a long job and
+  hands it to a second worker.
+- **The attempts ceiling is in the claim**, so a job that always crashes ends as failed instead of
+  restarting forever.
+- **Delivery is at-least-once**: a worker can die after the side effect and before the commit. The job
+  is idempotent.
+- **An integration test runs the claim against a real Postgres.** Two workers, one job, one winner: a
+  fake store proves nothing about locks.
+- **A partial index covers the eligible rows**, and finished jobs leave the table on a schedule. Dead
+  rows at the head of the queue are the first thing that degrades a Postgres queue.
+
 ---
 
 ## Feature Error Factory

package/framework/standards/backend/integrations/hangfire/hangfire-jobs.md

@@ -5,7 +5,7 @@
 > **Keywords:** hangfire, background job, recurring, fire-and-forget, scheduled
 > **Load When:** hangfire or background job keywords detected
 
-**Verified against:** .NET 10 (SDK 10.0.400-preview) + Hangfire.Core/Hangfire.AspNetCore 1.8.25 + Hangfire.PostgreSql 1.21.1 + Newtonsoft.Json 13.0.4. The startup, job/handler, dashboard-filter and idempotency blocks compile with `TreatWarningsAsErrors`; the Job Types calls compile inside a wrapper method; the per-job DI scope (`AspNetCoreJobActivator` → `IServiceScopeFactory`) and the `PostgreSqlStorageOptions` defaults were read by reflection on those assemblies; the pooled-endpoint limits (LISTEN/NOTIFY, migrations on the direct string) come from the Neon connection-pooling docs. Cron strings are documentary. Last-verified: 2026-10-03.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Hangfire.Core/Hangfire.AspNetCore 1.8.25 + Hangfire.PostgreSql 1.21.1 + Newtonsoft.Json 13.0.4. The startup, job/handler, dashboard-filter and idempotency blocks compile with `TreatWarningsAsErrors`; the Job Types calls compile inside a wrapper method; the per-job DI scope (`AspNetCoreJobActivator` → `IServiceScopeFactory`) and the `PostgreSqlStorageOptions` defaults were read by reflection on those assemblies; the pooled-endpoint limits (LISTEN/NOTIFY, migrations on the direct string) come from the Neon connection-pooling docs. Cron strings are documentary. Scale-to-zero behaviour read from the Neon docs. Last-verified: 2026-10-30.
 
 ---
 
@@ -75,6 +75,7 @@ app.Run();
 - **Storage on Neon Postgres** (`Hangfire.PostgreSql`), not SQL Server. The `UsePostgreSqlStorage(string, ...)` overloads are `[Obsolete]` in 1.21; use the `options => options.UseNpgsqlConnection(...)` form above.
 - **`HangfireConnection` points at the direct (unpooled) Neon endpoint**, like migrations (`infrastructure/neon/neon-setup.md`): the storage installs its schema at startup (`PrepareSchemaIfNecessary = true` by default), and Neon recommends the direct string for migrations; and if you turn on `EnableLongPolling` it uses `LISTEN/NOTIFY`, which Neon's PgBouncer (transaction mode) does not support.
 - Defaults read from `PostgreSqlStorageOptions` 1.21.1: `SchemaName = "hangfire"`, `QueuePollInterval = 15 s`, `InvisibilityTimeout = 30 min`, `DistributedLockTimeout = 10 min`, `EnableLongPolling = false`.
+- **Polling keeps a Neon compute awake.** Neon suspends after 5 minutes without queries, and the 15 s `QueuePollInterval` never lets that happen: a Hangfire server, or any worker polling a queue table, means an always-on compute. Weigh that cost in the plan before adding a worker to a project that relies on scale to zero. `pg_cron` only runs while the compute is active, and an idle `LISTEN` connection also disables scale to zero.
 - The connection string comes from configuration (user-secrets in development, Coolify environment variables in production), never from code.
 
 ---

package/framework/standards/backend/integrations/neon-auth/neon-auth.md

@@ -5,7 +5,9 @@
 > **Keywords:** neon auth, better auth, authentication, nextjs, user management, session, JWT, trusted origins, EdDSA, Ed25519, BouncyCastle, signature validator, jwks, middleware runtime, api prefix, data api, postgrest, bypass backend, direct database access
 > **Load When:** neon auth or authentication keywords detected
 
-**Verified against:** Neon Auth — @neondatabase/auth + @neondatabase/auth-ui (Better Auth). Last-verified: 2026-07-13.
+**Verified against:** Neon Auth — @neondatabase/auth + @neondatabase/auth-ui (Better Auth), run on 2026-07-13; package names of `createNeonAuth`/`createAuthClient` and the install line read from the Neon quickstart for `@neon/auth` 0.8.x, not run. Last-verified: 2026-10-30.
+
+> **Pacote novo:** o SDK agora é `@neon/auth` (0.8.1 ou superior), e o produto chama Managed Better Auth. Projeto novo usa ele, com os componentes do Better Auth UI copiados pelo shadcn CLI (`docs/auth/reference/ui-components`). As seções de UI abaixo descrevem `@neondatabase/auth-ui`, que está deprecado: valem para os projetos que ainda o usam.
 
 > This standard is the reference implementation, not a troubleshooting log. Every section below
 > exists because a real end-to-end run in a production project (2026-07-13) hit the failure mode it documents. See [Known Failure Modes](#known-failure-modes-postmortem)
@@ -77,14 +79,13 @@ should have direct access by default.
 ### Install Packages
 
 ```bash
-# Core auth + UI components are separate packages
-npm install @neondatabase/auth@latest @neondatabase/auth-ui @neondatabase/serverless
+npm install @neon/auth@latest
 ```
 
-> The UI components (`AuthView`, `UserButton`, `SignedIn`, `SignedOut`,
-> `RedirectToSignIn`) live in `@neondatabase/auth-ui`, not in the core
-> `@neondatabase/auth` package. The legacy `@stackframe/stack` packages and
-> `@neondatabase/neon-auth-next` are deprecated — do not install them.
+> In projects still on the old packages, the UI components (`AuthView`, `UserButton`,
+> `SignedIn`, `SignedOut`, `RedirectToSignIn`) live in `@neondatabase/auth-ui`. The legacy
+> `@stackframe/stack` packages and `@neondatabase/neon-auth-next` are deprecated — do not
+> install them.
 
 ### Environment Variables
 
@@ -129,7 +130,7 @@ React hooks are re-exported from the client instance for ergonomic imports:
 
 ```typescript
 'use client';
-import { createAuthClient } from '@neondatabase/auth/next';
+import { createAuthClient } from '@neon/auth/next';
 export const authClient = createAuthClient(process.env.NEXT_PUBLIC_AUTH_URL!);
 export const { useSession } = authClient;
 ```
@@ -137,7 +138,7 @@ export const { useSession } = authClient;
 `lib/auth/server.ts`:
 
 ```typescript
-import { createNeonAuth } from '@neondatabase/auth/next/server';
+import { createNeonAuth } from '@neon/auth/next/server';
 export const auth = createNeonAuth({
   baseUrl: process.env.NEON_AUTH_BASE_URL!,
   cookies: {

package/framework/standards/infrastructure/docker/local-compose-isolation.md

@@ -5,7 +5,7 @@
 > **Keywords:** docker compose, worktree, ports, container_name, POSTGRES_PORT, COMPOSE_PROJECT_NAME, local dev, e2e stack
 > **Load When:** a compose file, a dev-server port, or a worktree stack is being written or debugged
 
-**Verified against:** Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree). Last-verified: 2026-09-08.
+**Verified against:** Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree). The `pgvector/pgvector:pg17` tag was confirmed on Docker Hub; the image was not run. Last-verified: 2026-10-30.
 
 ---
 
@@ -86,7 +86,7 @@ services:
       timeout: 5s
       retries: 12
   postgres:
-    image: postgres:15-alpine
+    image: pgvector/pgvector:pg17
     ports:
       - "${POSTGRES_PORT:-5432}:5432"
     environment:

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

@@ -2,10 +2,10 @@
 
 > **Scope:** neon, dotnet-vsa
 > **Layer:** 1 (on scope)
-> **Keywords:** pgvector, vector, embeddings, similarity search, HNSW, cosine
+> **Keywords:** pgvector, vector, embeddings, similarity search, HNSW, cosine, hybrid search, busca híbrida, RRF, BM25, full-text, lakebase, pg_search
 > **Load When:** pgvector or embedding keywords detected
 
-**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.
+**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`, `match_documents`) is documentary, checked against the pgvector README; `hybrid_search` ran on PGlite 0.5.13, not on a Neon compute; the `unaccent` dictionary in a text search configuration is what the Neon `unaccent` page describes (only `unaccent.rules` is closed); Lakebase Search read from the Neon docs. Last-verified: 2026-10-30.
 
 ---
 
@@ -218,38 +218,80 @@ $$;
 
 ## Hybrid Search (Vector + Full-Text)
 
-Blends the vector score with `ts_rank`. Same rule as above: a SQL function, justified in `plan.md` (`## Decisões`).
+Semantic search alone misses exact terms (SKU, name, code, error message). Keyword search alone misses paraphrases. Run both and fuse the **ranks** with Reciprocal Rank Fusion: cosine distance and text rank live on different scales, so a weighted sum of the two scores is meaningless. Same rule as above: a SQL function, justified in `plan.md` (`## Decisões`).
+
+The default runs on Neon and on the local Docker Postgres alike: native full-text search over a generated `tsvector` with a GIN index. Computing `to_tsvector` inline in the query never uses the index. Content in pt-BR needs its own configuration, or `devolucao` never matches `devolução`:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS unaccent;
+
+CREATE TEXT SEARCH CONFIGURATION pt_unaccent (COPY = portuguese);
+ALTER TEXT SEARCH CONFIGURATION pt_unaccent
+  ALTER MAPPING FOR hword, hword_part, word WITH unaccent, portuguese_stem;
+
+ALTER TABLE documents ADD COLUMN search_tsv tsvector
+  GENERATED ALWAYS AS (to_tsvector('pt_unaccent', title || ' ' || content)) STORED;
+
+CREATE INDEX idx_documents_search_tsv ON documents USING gin (search_tsv);
+```
 
 ```sql
 CREATE OR REPLACE FUNCTION hybrid_search(
   query_text text,
   query_embedding vector(1536),
   match_count int DEFAULT 10,
-  text_weight float DEFAULT 0.3,
-  vector_weight float DEFAULT 0.7
-) RETURNS TABLE (id uuid, title text, content text, score float)
+  candidate_count int DEFAULT 50,
+  rrf_k int DEFAULT 60
+) RETURNS TABLE (id uuid, title text, content text, score double precision)
 LANGUAGE sql STABLE AS $$
   WITH vector_results AS (
-    SELECT id, title, content,
-      1 - (embedding <=> query_embedding) AS vector_score
-    FROM documents
-    ORDER BY embedding <=> query_embedding LIMIT match_count * 2
+    SELECT c.id, row_number() OVER (ORDER BY c.distance) AS rank
+    FROM (
+      SELECT d.id, d.embedding <=> query_embedding AS distance
+      FROM documents d
+      ORDER BY distance
+      LIMIT candidate_count
+    ) c
   ),
   text_results AS (
-    SELECT id, title, content,
-      ts_rank(to_tsvector('english', content), plainto_tsquery('english', query_text)) AS text_score
-    FROM documents
-    WHERE to_tsvector('english', content) @@ plainto_tsquery('english', query_text)
-    LIMIT match_count * 2
+    SELECT c.id, row_number() OVER (ORDER BY c.text_score DESC) AS rank
+    FROM (
+      SELECT d.id, ts_rank_cd(d.search_tsv, q.query) AS text_score
+      FROM documents d, websearch_to_tsquery('pt_unaccent', query_text) AS q(query)
+      WHERE d.search_tsv @@ q.query
+      ORDER BY text_score DESC
+      LIMIT candidate_count
+    ) c
+  ),
+  fused AS (
+    SELECT COALESCE(v.id, t.id) AS id,
+      COALESCE(1.0 / (rrf_k + v.rank), 0) + COALESCE(1.0 / (rrf_k + t.rank), 0) AS score
+    FROM vector_results v
+    FULL OUTER JOIN text_results t ON v.id = t.id
   )
-  SELECT COALESCE(v.id, t.id), COALESCE(v.title, t.title), COALESCE(v.content, t.content),
-    (COALESCE(v.vector_score, 0) * vector_weight + COALESCE(t.text_score, 0) * text_weight) AS score
-  FROM vector_results v FULL OUTER JOIN text_results t ON v.id = t.id
-  ORDER BY score DESC LIMIT match_count;
+  SELECT d.id, d.title, d.content, f.score::double precision
+  FROM fused f
+  JOIN documents d ON d.id = f.id
+  ORDER BY f.score DESC
+  LIMIT match_count;
 $$;
 ```
 
-For Portuguese content use the `'portuguese'` text search configuration in both `to_tsvector` and `plainto_tsquery`.
+- Multi-tenant table: filter the tenant in **both** inner queries, never only after the fusion.
+- `websearch_to_tsquery` accepts raw user text. `to_tsquery` errors on plain phrases.
+- Both the SQL above and its behaviour (accent-insensitive match, exact code ranked first, empty keyword branch) were run on PGlite 0.5.13 (PostgreSQL 18, pgvector 0.8.7).
+
+### Lakebase Search (Neon-only upgrade)
+
+`pg_search` (ParadeDB) is gone from Neon: installs blocked on 2026-03-19, removed on 2026-09-21. Its replacement is `lakebase_text` (PostgreSQL 16+), which adds real BM25 ranking on the same `tsvector` column. `lakebase_vector` adds the `lakebase_ann` index over the same `vector` columns for scale. Neither exists in the local Docker Postgres, so adopting one is an ADR in `plan.md` (`## Decisões`) that says how dev and tests run. Reach for them only when an eval shows `ts_rank_cd` ranks badly, or the corpus outgrows HNSW.
+
+Traps of `lakebase_text`:
+
+- `<@>` only scores: filter with `@@` in the `WHERE`, or every row comes back.
+- The score is negative: `ORDER BY score` ascending, best first. RRF is unaffected, since it reads ranks.
+- `to_bm25query` takes the index name, because the corpus statistics live in the index.
+- Create the index after the initial load and run `VACUUM` after bulk loads. The statistics are not MVCC-versioned, so scores can shift under a concurrent `VACUUM`.
+- There is no fuzzy match (`pg_trgm` covers typos) and no `paradedb.snippet()` (`ts_headline` covers highlighting).
 
 ## Npgsql Vector Type Handler
 

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

@@ -0,0 +1,61 @@
+# Neon — o que a plataforma entrega pronto
+
+> **Scope:** neon
+> **Layer:** 1 (resumo injetado pela rule `neon-standards`; lido no plano antes de contratar serviço novo)
+> **Keywords:** neon, plataforma, branch, snapshot, PITR, restore, object storage, s3, ai gateway, read replica, slow query, query tuning, ip allow, protected branch, região, neon cli
+> **Load When:** projeto com `neon` precisa de arquivo, gateway de LLM, ambiente descartável, rede de segurança de migration, diagnóstico de consulta ou leitura pesada
+
+**Verified against:** Neon docs lidas em 2026-10-30 (regions, plans, backup-restore, branch-expiration, s3-compatibility, ai-gateway, neon-mcp-server, functions) + CLI `neon` 8.14.0. Nenhum bloco deste standard foi executado contra um projeto. Last-verified: 2026-10-30.
+
+---
+
+Antes de escrever código ou contratar serviço, confira se o Neon do projeto já resolve. Preço, plano e status mudam rápido: em dúvida, `mcp__neon__search_docs`.
+
+## Região decide o catálogo
+
+A região é fixa na criação do projeto; mudar é criar outro projeto e migrar. Postgres e Auth existem em todas. O resto não:
+
+| Região | Storage, Functions, AI Gateway, Realtime |
+| --- | --- |
+| `aws-us-east-1`, `aws-us-east-2`, `aws-eu-central-1`, `aws-ap-southeast-1` | Sim |
+| `aws-sa-east-1`, `aws-us-west-2`, `aws-eu-west-2`, `aws-ap-southeast-2` | Não |
+
+`neon projects get <id>` mostra o `region_id`. Projeto em São Paulo fica sem esses quatro produtos: pese isso antes de escolher a região pela latência.
+
+## Necessidade → o que usar
+
+| Necessidade | No Neon | Pegadinha |
+| --- | --- | --- |
+| Testar migration ou dado real sem tocar produção | Branch com `--expires-at` (máx. 30 dias), `neon branches reset --parent` para recomeçar | Reset sobrescreve o branch, sem backup. `--schema-only` está em beta e não tem pai, logo não tem reset |
+| Ensaiar migration | MCP `prepare_database_migration` → `complete_database_migration` | Aplica SQL em branch temporário: confere o SQL gerado pelo `dotnet ef migrations script --idempotent`, não substitui o `dotnet ef` |
+| Ver o que mudou no schema | `neon branches schema-diff`, `neon diff`, MCP `compare_database_schema` | Compara, não aplica |
+| Rede de segurança de migration com `degrau:` | Snapshot manual antes de aplicar (MCP `create_snapshot`, `neon snapshots`); volta por PITR dentro da janela | Janela default curta (6 h no Free, 1 dia nos pagos, ajustável). Só root branch. Branch restaurado de snapshot perde PITR |
+| Arquivo do usuário, mídia gerada | Object Storage, S3-compatible, GA | `$0,023/GB-mês`. Lifecycle e versioning são guardados, não aplicados. Sem notificação de bucket. Cliente .NET por S3 path-style não testado aqui |
+| Uma credencial para vários modelos de LLM | AI Gateway, OpenAI-compatible, GA | Plano pago e crédito pré-pago. Foge do padrão de provider direto do `model-registry`: exige ADR |
+| Busca por termo em escala | Lakebase Search (`infrastructure-neon-pgvector#lakebase-search-neon-only-upgrade`) | Só existe no Neon |
+| Consulta lenta | MCP `list_slow_queries`, `explain_sql_statement`, `prepare_query_tuning` → `complete_query_tuning`; `pg_stat_statements` | Histórico some quando o compute suspende. `query tuning` testa índice em branch |
+| Relatório pesado sem pesar no primário | Read replica, com connection string própria | Eventualmente consistente, mesma região, cobra compute |
+| Fechar o banco ao IP da VPS | IP Allow, só plano Scale | Incompatível com Neon Auth e Data API: quem usa Auth não liga |
+| Impedir que apaguem produção | Protected branch (Launch: 2, Scale: 5) | Filhos ganham senha nova e scripts de CI quebram |
+| Alerta e métrica fora do console | Export OTel/Datadog, só Scale, em beta | Lacuna enquanto o compute está suspenso |
+
+## O que não adotar nesta stack
+
+- **Neon Functions para job .NET:** só JS/TS, e a doc diz "They aren't a job queue". Serve para schedule em UTC que faz POST num endpoint idempotente.
+- **Data API:** o EF Core já é o acesso. Sem autorização própria além de `GRANT`/RLS.
+- **Realtime:** beta, sem RLS, SDK só TypeScript.
+- **Neon Local:** é proxy para a nuvem, não Postgres local. Dev segue no Docker Compose (`infrastructure-docker-local-compose-isolation`).
+- **Private Networking:** exige o cliente na AWS, na mesma região. A VPS não está.
+- **Logical replication sem necessidade real:** reinicia computes e `wal_level` é irreversível.
+
+## MCP em produção
+
+A doc do Neon é explícita: "Never connect MCP agents to production databases". O agente trabalha em branch. O servidor expõe tools destrutivas, e toda escrita em produção passa por um humano, com snapshot antes quando houver `degrau:`.
+
+## CLI
+
+O pacote agora é `neon` (`npm i -g neon`, Node 20.19+). `neonctl` segue funcionando como o mesmo binário. Login é `neon login`. Comandos úteis no dia a dia: `neon branches`, `neon diff`, `neon snapshots`, `neon psql`, `neon logs`, `neon buckets`, `neon connection-string`, `neon checkout`, `neon env pull`. `neon.ts` (`neon config init`) declara branches em TypeScript: útil no front, opcional em projeto .NET, que lê `user-secrets`.
+
+## Fora do catálogo
+
+`pg_search` foi removido, `pgrag` e `plv8` estão deprecados, `pgmq` e Apache AGE não estão na lista de extensões. Lista viva: `docs/extensions/pg-extensions`.

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

@@ -2,10 +2,10 @@
 
 > **Scope:** neon
 > **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
+> **Keywords:** neon, serverless postgres, branching, scale-to-zero, connection string, neon cli, neonctl
 > **Load When:** neon stack detected
 
-**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.
+**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). `neon` CLI commands are documentary; the top-level commands were read from `neon --help` 8.14.0. Last-verified: 2026-10-30.
 
 ---
 
@@ -18,19 +18,20 @@ Stack: .NET + Neon Serverless Postgres
 - 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
+- NEVER leave branches without expiration -- set TTL for dev/CI branches (`--expires-at`, 30 days at most)
+- ALWAYS take a snapshot before applying a migration with `degrau:` to production (`infrastructure-neon-platform`)
 
 ## Neon CLI Setup
 
 ```bash
-# Install neonctl globally
-npm install -g neonctl
+# Install neon globally
+npm install -g neon
 
 # Authenticate (opens browser)
-neonctl auth
+neon login
 
 # Verify connection
-neonctl projects list
+neon projects list
 ```
 
 ## Connection Strings
@@ -130,24 +131,24 @@ Neon branches are copy-on-write clones of your database -- instant, zero-cost un
 
 ```bash
 # List branches
-neonctl branches list --project-id <project-id>
+neon branches list --project-id <project-id>
 
 # Create feature branch from main
-neonctl branches create --project-id <project-id> \
+neon 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> \
+neon branches create --project-id <project-id> \
   --name ci-test-run-42 \
   --parent main \
   --expires-at "2027-01-01T00:00:00Z"
 
 # Reset branch to parent state
-neonctl branches reset feature/my-feature --parent --project-id <project-id>
+neon branches reset feature/my-feature --parent --project-id <project-id>
 
 # Delete branch
-neonctl branches delete feature/my-feature --project-id <project-id>
+neon branches delete feature/my-feature --project-id <project-id>
 ```
 
 ### Branch Strategy
@@ -189,7 +190,7 @@ Set it when the branch (and its compute) is created; `main` already exists, so i
 
 ```bash
 # New branch with a 10-minute suspend timeout and an autoscaling range
-neonctl branches create --project-id <project-id> \
+neon branches create --project-id <project-id> \
   --name feature/my-feature \
   --parent main \
   --suspend-timeout 600 \

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

@@ -5,7 +5,7 @@
 > **Keywords:** mcp, model-context-protocol, mcp-tools, context7, playwright, mcp-client
 > **Load When:** an MCP tool is used in any morph-spec phase
 
-**Verified against:** Claude Code 2.1.282 MCP tooling — context7, Playwright (as plugin and as a project MCP server); GitHub via `gh` CLI; Neon via its MCP or `neonctl`; Microsoft Learn MCP (`https://learn.microsoft.com/api/mcp`, tools listed by `tools/list` on 2026-10-17). Last-verified: 2026-10-17.
+**Verified against:** Claude Code 2.1.282 MCP tooling — context7, Playwright (as plugin and as a project MCP server); GitHub via `gh` CLI; Neon via its MCP or `neon`; Microsoft Learn MCP (`https://learn.microsoft.com/api/mcp`, tools listed by `tools/list` on 2026-10-17). Last-verified: 2026-10-30.
 
 ---
 
@@ -19,7 +19,7 @@ In a morph persona the grant follows the same rule: the installer emits one `mcp
 
 ## MCP Availability Detection
 
-Before using any MCP tool, check if it's available in the current session. There is no "list MCPs" command: attempt the most common operation, and Claude Code reports a tool that doesn't exist. GitHub and Neon are not checked this way — o morph-spec NÃO usa MCP do GitHub nem do Neon: use o `gh` CLI (`gh repo view --json name,defaultBranchRef,languages`) e o `neonctl` + `psql` (`neonctl connection-string` dá a URL do banco) via Bash.
+Before using any MCP tool, check if it's available in the current session. There is no "list MCPs" command: attempt the most common operation, and Claude Code reports a tool that doesn't exist. GitHub and Neon are not checked this way — o morph-spec NÃO usa MCP do GitHub nem do Neon: use o `gh` CLI (`gh repo view --json name,defaultBranchRef,languages`) e o `neon` + `psql` (`neon connection-string` dá a URL do banco) via Bash.
 
 ```javascript
 await mcp__context7__resolve-library-id({ libraryName: "react" });
@@ -136,7 +136,7 @@ Fallback: manual image creation, stock photos, or placeholder divs.
 
 | Tool | Use Case | Example |
 |------|----------|---------|
-| **Neon CLI (`neonctl`) / psql** | Database schema, tables, relationships, RLS | `psql <DB_URL> -c "SELECT ..."` |
+| **Neon CLI (`neon`) / psql** | Database schema, tables, relationships, RLS | `psql <DB_URL> -c "SELECT ..."` |
 | **Context7** | Library docs for architecture decisions | `mcp__context7__query-docs()` |
 | **Microsoft Learn** (stack .NET) | Official docs for a .NET/EF Core/MAF decision (limits, what is new, migration) | `mcp__microsoft-learn__microsoft_docs_search({ query })` |
 | **GitHub CLI (`gh`)** | Check existing code patterns, PRs | `gh search code` (Bash) |
@@ -145,25 +145,25 @@ Fallback: manual image creation, stock photos, or placeholder divs.
 # === SCHEMA ANALYSIS (Critical for contracts.cs) ===
 
 # 0. Get Neon DB connection string
-neonctl connection-string
+neon connection-string
 # → e.g.: postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require
 
 # 1. List all tables
-pg_dump $(neonctl connection-string) --schema-only --schema public 2>/dev/null | grep "CREATE TABLE"
+pg_dump $(neon connection-string) --schema-only --schema public 2>/dev/null | grep "CREATE TABLE"
 
 # 2. Get schema for each relevant table
-psql $(neonctl connection-string) -c "SELECT column_name, data_type, is_nullable, column_default \
+psql $(neon 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 $(neonctl connection-string) -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table, \
+psql $(neon 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 $(neonctl connection-string) -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
+psql $(neon connection-string) -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
 ```
 
 **Fallback (Neon database not accessible):**
@@ -211,7 +211,7 @@ gh issue create --title "F1: Create Entity Lead" \
 
 | Tool | Use Case | Example |
 |------|----------|---------|
-| **Neon CLI (`neonctl`) / psql** | Run migrations, create RLS policies | `dotnet ef database update` |
+| **Neon CLI (`neon`) / psql** | Run migrations, create RLS policies | `dotnet ef database update` |
 | **GitHub CLI (`gh`)** | Create PR, push branches | `gh pr create` (Bash) |
 | **Context7** | Look up API usage during coding | `mcp__context7__query-docs()` |
 | **Microsoft Learn** (stack .NET) | Current .NET 10 / EF Core / ASP.NET Core / MAF API: search, then fetch the page when the excerpt is cut | `mcp__microsoft-learn__microsoft_docs_search({ query })` → `microsoft_docs_fetch({ url })`; `microsoft_code_sample_search` for snippets |
@@ -230,10 +230,10 @@ dotnet ef migrations add AddStatusToLeads
 dotnet ef database update
 
 # Verify schema after migration
-psql $(neonctl connection-string) -c "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'leads'"
+psql $(neon connection-string) -c "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'leads'"
 
 # Verify RLS policies
-psql $(neonctl connection-string) -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
+psql $(neon 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 the slice report (`3-implement/reports/F{n}.md`). Vercel covers deployment status, logs and environment variables.
@@ -270,7 +270,7 @@ PRs/issues: sempre `gh` CLI (Bash). Deployments fallback: `vercel` CLI.
 
 | Need | MCP Tool | Native Alternative |
 |------|----------|--------------------|
-| Database schema | Neon CLI (`neonctl`) / psql | Grep queries + Read types |
+| Database schema | Neon CLI (`neon`) / psql | Grep queries + Read types |
 | Repo metadata / issues / PRs | Bash `gh` CLI | WebFetch `api.github.com` (read-only) |
 | Library docs | Context7 | WebSearch + WebFetch |
 | Live page preview | Playwright MCP | WebFetch URL |
@@ -335,26 +335,26 @@ await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/fil
 
 ---
 
-### Neon: Full Schema Discovery (via neonctl + psql)
+### Neon: Full Schema Discovery (via neon + psql)
 
-> **Primary:** Neon CLI (`neonctl`) + psql connecting to Neon database.
-> **Connection:** Always use `neonctl connection-string` to get the DB URL.
+> **Primary:** Neon CLI (`neon`) + psql connecting to Neon database.
+> **Connection:** Always use `neon connection-string` to get the DB URL.
 
 ```bash
 # Complete workflow for Phase 3 schema analysis
 
 # 1. Get Neon DB URL
-neonctl connection-string  # → pooled connection string
+neon connection-string  # → pooled connection string
 
 # 2. List all tables
-pg_dump $(neonctl connection-string) --schema-only --schema public 2>/dev/null | grep "CREATE TABLE"
+pg_dump $(neon connection-string) --schema-only --schema public 2>/dev/null | grep "CREATE TABLE"
 
 # 3. For each relevant table:
-psql $(neonctl connection-string) -c "SELECT column_name, data_type, is_nullable, column_default \
+psql $(neon 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 $(neonctl connection-string) -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table \
+psql $(neon 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 +397,7 @@ gh api repos/{owner}/{repo}/branches --jq '.[].name'
 ## Security Considerations
 
 - **Never pass secrets** in MCP tool parameters (API keys, tokens, passwords)
-- **Neon** uses neonctl/psql — use database branches for development, not production
+- **Neon** uses neon/psql — use database branches for development, not production
 - **GitHub via `gh` CLI** herda as permissões do login do `gh auth login` (keyring) — sem PAT em env var, sem Docker
 - **Always validate tool responses** before using in contracts or code generation
 

package/framework/templates/docs/plan.md

@@ -7,6 +7,8 @@
 
 <O que dói hoje, para quem, e como se percebe. Duas a cinco frases.>
 
+Resultado buscado: <o estado depois: o que muda, para quem, como se percebe.>
+
 ## Fora de escopo
 
 - <o que esta feature deliberadamente não faz>
@@ -69,6 +71,7 @@ nenhum
 
 ## Contrato de implementação
 
-<Assinaturas, records, enums e rotas que a implementação honra; runtime do e2e; baseline de teste como comando.>
+- **Instrumentos:** <o que falta para provar sozinho: ferramenta, acesso, dado, ambiente; "nenhuma lacuna" vale.>
+- <Assinaturas, records, enums e rotas que a implementação honra; runtime do e2e; baseline de teste como comando.>
 
 ## Errata