@polymorphism-tech/morph-spec 10.0.0 → 10.1.1

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

package/framework/templates/infrastructure/docker/docker-compose.template.yml

@@ -56,7 +56,7 @@ services:
 
   # PostgreSQL Database (Local development)
   postgres:
-    image: postgres:15-alpine
+    image: pgvector/pgvector:pg17
     restart: unless-stopped
     ports:
       - "${POSTGRES_PORT:-5432}:5432"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "10.0.0",
+  "version": "10.1.1",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/state/auto-approval.js

@@ -30,7 +30,7 @@ export function autoApprovalRefusal({ cwd, featureName, feature, gate, approvedB
   }
 
   if (gate === 'plan') {
-    const block = planAutoApprovalBlock(cwd, featureName);
+    const block = planAutoApprovalBlock(cwd, featureName, feature);
     if (block) {
       return {
         title: `O gate "plan" não pode ser auto-aprovado — ${block}.`,

package/src/commands/state/create.js

@@ -132,7 +132,7 @@ export async function createCommand(featureName, options = {}) {
     const alreadyExists = existsSync(join(process.cwd(), '.morph', 'features', featureName, 'feature.json'));
     if (!alreadyExists && (description === null || String(description).trim() === '')) {
       console.error(chalk.red(`\n❌ A feature needs a description at birth: "${featureName}"`));
-      console.error(chalk.gray('   Pass --description "<what/why>" (or --request "<pedido>", which seeds it).'));
+      console.error(chalk.gray('   Pass --description "<what/why>" (or --request '<pedido>', which seeds it).'));
       console.error(chalk.gray('   This keeps features identifiable — no more anonymous scaffolds.\n'));
       process.exit(1);
     }

package/src/commands/state/gate-check.js

@@ -59,9 +59,9 @@ export function collectReviewSignal(cwd, featureName, feature, planChecks = read
 }
 
 /** Why an automatic signature may not close the plan gate: the rule that makes gate-check pause it. */
-export function planAutoApprovalBlock(cwd, featureName) {
+export function planAutoApprovalBlock(cwd, featureName, feature) {
   const planChecks = readPlanChecks(cwd, featureName);
-  const workType = getFeature(featureName)?.workType || 'feature';
+  const workType = feature?.workType || 'feature';
   const reason = planChecksPause(planChecks.status)
     ?? planCritiquePause(readPlanCritique(cwd, featureName, { workType, planChecks }))
     ?? rungPause({ gate: 'plan', rungs: pausingRungs(planChecks.checks) })?.reason;

package/src/lib/detectors/index.js

@@ -54,7 +54,7 @@ export function detectProject(targetPath, opts = {}) {
       if (depNames.includes('@neondatabase/serverless') || depNames.includes('postgres') || depNames.includes('pg')) {
         structure.integrations.push('neon');
       }
-      if (depNames.includes('@neondatabase/auth')) {
+      if (depNames.includes('@neon/auth') || depNames.includes('@neondatabase/auth')) {
         structure.integrations.push('neon-auth');
       }
       if (depNames.includes('stripe')) {

package/src/lib/installers/memory-installer.js

@@ -39,7 +39,7 @@ metadata:
 
 | Command | Skill invoked |
 |---------|---------------|
-| \`/morph-plan {feature}\` | \`Skill(morph-plan)\` — entrevista → plan.md → plan-check → gate do plano |
+| \`/morph-plan {feature}\` | \`Skill(morph-plan)\` — tese → plan.md → plan-check → gate do plano |
 | \`/morph-apply {feature}\` | \`Skill(morph-apply)\` — fatias do plano → verify → review → Gate 3 |
 | \`/morph-status [feature]\` | inspect state.json |
 | \`/morph-archive {feature}\` | move completed feature to .morph/archive/ |

package/src/lib/plan/checks.js

@@ -123,9 +123,16 @@ export function validatePlan(plan, { workType = null, riskRules = true, text = n
   errors.push(...statesErrors(plan, at));
   warnings.push(...defaultsWarnings(plan, at));
 
-  if (plan.sections.some((s) => !s.key && /^fatias$/i.test(s.name.trim()))) {
+  const isSlices = (s) => /^fatias$/i.test(s.name.trim());
+  if (plan.sections.some((s) => !s.key && isSlices(s))) {
     warnings.push('## Fatias não é lida desde a 10.0: o plano inteiro se implementa numa sessão, e os cenários definem o pronto');
   }
+  const known = new Set(Object.values(SECTIONS).map(foldRisk));
+  for (const s of plan.sections.filter((section) => !section.key && !isSlices(section))) {
+    warnings.push(known.has(foldRisk(s.name))
+      ? `## ${s.name} repetida${at(s.line)} — só a primeira é lida, o conteúdo desta se perde`
+      : `## ${s.name} não é seção do plano${at(s.line)} — o plan-check não a lê`);
+  }
 
   for (const r of plan.reuse) {
     if (!REUSE_VERDICTS.includes(r.verdict)) {