@polymorphism-tech/morph-spec 9.8.0 → 10.1.1

package/framework/standards/ai-agents/rag-custom-pgvector.md

@@ -216,10 +216,10 @@ The agent decides autonomously when to call `VectorSearchTool.SearchAsync`. It r
 
 ## Ingestão delta por lookup-key
 
-**O defeito que esta seção existe para matar é o apaga-e-regrava.** `KbStore.IngestAsync` do GHLBrain faz `DELETE … WHERE location_id AND source` e re-insere/re-embeda **tudo** do `source` a cada ingestão, mudou ou não (`docs/specs/elevacao-9/brutos/scan-ghlbrain.md:412`): 288 fichas re-embedadas, uma chamada de embedding por item, a cada reindex em massa do catálogo — e, com id posicional, inserir um trecho no topo de um documento torna "novos" todos os de baixo.
+**O defeito que esta seção existe para matar é o apaga-e-regrava.** O `KbStore.IngestAsync` de um projeto em produção faz `DELETE … WHERE location_id AND source` e re-insere/re-embeda **tudo** do `source` a cada ingestão, mudou ou não: 288 fichas re-embedadas, uma chamada de embedding por item, a cada reindex em massa do catálogo — e, com id posicional, inserir um trecho no topo de um documento torna "novos" todos os de baixo.
 
-> [!warning] Errata (2026-09-15, medida no código e no Neon de produção — Morph.GHLBrain#96)
-> A versão anterior deste parágrafo afirmava também uma **janela** entre o apagar e o gravar em que a busca não acha nada. **No GHLBrain ela não existe:** `ConvVectorSql.ExecuteAsync` roda o `DELETE` e os `INSERT`s numa transação só, e o embedding acontece **antes** de a transação abrir — em READ COMMITTED o leitor vê o conteúdo antigo até o commit. O custo medido também é pequeno (324 trechos, ~US$ 0,0005 por re-embed completo, 1 trecho por `source`): lá, o ganho real do delta é **latência** (o reindex em massa) e **prevenção** (documento de até ~70 trechos). A janela é real em quem apaga fora da transação que grava — é o caso que a regra 4 abaixo cobre.
+> [!warning] Errata (2026-09-15, medida no código e no Neon de produção)
+> A versão anterior deste parágrafo afirmava também uma **janela** entre o apagar e o gravar em que a busca não acha nada. **Nesse projeto ela não existe:** `ConvVectorSql.ExecuteAsync` roda o `DELETE` e os `INSERT`s numa transação só, e o embedding acontece **antes** de a transação abrir — em READ COMMITTED o leitor vê o conteúdo antigo até o commit. O custo medido também é pequeno (324 trechos, ~US$ 0,0005 por re-embed completo, 1 trecho por `source`): lá, o ganho real do delta é **latência** (o reindex em massa) e **prevenção** (documento de até ~70 trechos). A janela é real em quem apaga fora da transação que grava — é o caso que a regra 4 abaixo cobre.
 
 ### O contrato — uma função pura, sem I/O
 
@@ -251,7 +251,7 @@ public sealed record DeltaPlan<T>(
 1. **`Unchanged` não é re-embedado.** É a economia inteira. Num republish típico a lista grande é `Unchanged` e as outras três são curtas — e é exatamente isso que a ingestão anterior escondia.
 2. **`Removed` são as chaves presentes no acervo e ausentes do `incoming`.** Sem esse balde, conteúdo apagado na origem continua sendo devolvido pela busca.
 3. **O id continua determinístico** — `DeterministicUuid.V5(namespace, "{loc}:{source}:{idx}")` já é a prática — para que `Updated` seja **upsert**, não delete+insert. Delete+insert quebra referências e troca o id de um chunk que só mudou de texto.
-   **Ressalva medida (Morph.GHLBrain#96, ADR-2 da `delta-ingestion`):** quando o item é um *trecho* de documento, a posição como lookup-key derrota a regra 1 — inserir um trecho no topo desloca os índices e marca todo trecho abaixo como `Updated`, re-embedando tudo. Ali a chave certa é o **hash do conteúdo** (`lookupKey` e `contentHash` recebem o mesmo delegado): `Updated` fica vazio por construção, editar um trecho vira `Added` + `Removed`, e trechos idênticos são deduplicados antes do `Plan` para a chave duplicada nunca disparar. A chave posicional continua certa quando o item tem identidade própria (uma ficha por produto, um documento inteiro).
+   **Ressalva medida em produção:** quando o item é um *trecho* de documento, a posição como lookup-key derrota a regra 1 — inserir um trecho no topo desloca os índices e marca todo trecho abaixo como `Updated`, re-embedando tudo. Ali a chave certa é o **hash do conteúdo** (`lookupKey` e `contentHash` recebem o mesmo delegado): `Updated` fica vazio por construção, editar um trecho vira `Added` + `Removed`, e trechos idênticos são deduplicados antes do `Plan` para a chave duplicada nunca disparar. A chave posicional continua certa quando o item tem identidade própria (uma ficha por produto, um documento inteiro).
 4. **Sem janela vazia: nunca apague antes de gravar fora da transação que grava.** Apagar e gravar em transações separadas (ou sem transação) é o que faz a busca devolver vazio durante a reingestão. Aplique `Added`/`Updated` primeiro e só então `Removed`, dentro da mesma transação — com a transação a janela já não existe, e a ordem mantém o código correto se um dia ela for partida.
 
 ### Chave duplicada no `incoming` é erro de entrada
@@ -273,7 +273,7 @@ Os dois não competem; resolvem problemas diferentes. Adote o writer quando acei
 
 ### Item aberto, medido em campo
 
-**Threshold de similaridade e `k` por escopo ainda não têm regra.** Hoje o escopo institucional da base do GHLBrain roda **sem `LIMIT`** (`scan-ghlbrain.md:410`): a busca devolve tudo o que passa do threshold, e o custo do prompt varia com o tamanho da base. Definir `k` e o corte por escopo é trabalho pendente, não recomendação existente — registrado aqui para não ser reinventado como se fosse novo.
+**Threshold de similaridade e `k` por escopo ainda não têm regra.** Hoje o escopo institucional da base desse projeto roda **sem `LIMIT`**: a busca devolve tudo o que passa do threshold, e o custo do prompt varia com o tamanho da base. Definir `k` e o corte por escopo é trabalho pendente, não recomendação existente — registrado aqui para não ser reinventado como se fosse novo.
 
 ---
 
@@ -301,6 +301,7 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 | Anti-pattern | Why it's wrong | Right way |
 |--------------|----------------|-----------|
 | Hosted RAG (upload PDFs to a service) | Loses control of chunking, embedding, and storage; vendor lock-in | Custom RAG: own all three layers |
+| Semantic search only, over a corpus with codes, SKUs or proper names | Embeddings blur exact terms; the right document never reaches the LLM | Hybrid search with RRF in the same Postgres (`infrastructure-neon-pgvector#hybrid-search-vector--full-text`), measured by eval |
 | Embeddings column without an index | Full table scan — 100 ms becomes 30 s at 100k rows | HNSW index on the embedding column always |
 | One fixed chunk size for all document types | Contracts need dense sentences; catalogs need short snippets; mixed chunks degrade recall | Choose strategy per document type (see `data-vector-search-rag-chunking`) |
 | `tenant_id` as a tool parameter the LLM passes | LLM can be prompted to pass any GUID — cross-tenant data leak | Inject `tenant_id` from auth context at construction; never expose as a model-facing parameter |
@@ -340,4 +341,4 @@ ALTER TABLE kb_embeddings ENABLE ROW LEVEL SECURITY;
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v2.1 (2026-09-15 — errata da janela no GHLBrain; ressalva da chave por hash)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/rag-custom-pgvector.md v2.1 (2026-09-15 — errata da janela; ressalva da chave por hash)*

package/framework/standards/ai-agents/setup.md

@@ -35,7 +35,7 @@ Está adicionando um agente AI a um projeto .NET?
 
 ## 1. Packages (NuGet)
 
-**Nenhuma faixa flutuante.** Um SDK de cadência semanal com `2.*` é como o ProspectPRO comprou um `MissingMethodException` na Responses API **depois de a chamada ser paga**. Versões abaixo: as do `framework/ai-pin.json` (`pinnedAt` 2026-09-08) ou, quando o pacote **não está no pin**, a versão apurada no nuget.org em **2026-09-08**, dita como tal.
+**Nenhuma faixa flutuante.** Um SDK de cadência semanal com `2.*` é como um projeto em produção comprou um `MissingMethodException` na Responses API **depois de a chamada ser paga**. Versões abaixo: as do `framework/ai-pin.json` (`pinnedAt` 2026-09-08) ou, quando o pacote **não está no pin**, a versão apurada no nuget.org em **2026-09-08**, dita como tal.
 
 **Required for any MAF project:**
 

package/framework/standards/ai-agents/tool-adapters.md

@@ -5,7 +5,7 @@
 > **Keywords:** tool, AIFunctionFactory, adaptador de tool, tool fina, Ops, Desfecho, Render, regra de negócio em tool, descrição da tool, golden de tool, refactor neutro, migração de teste
 > **Read by Claude in:** implement (ao escrever ou migrar uma tool de agente que carrega regra de negócio)
 
-**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm da feature `tools-finas` do MORPH_GHLBrain e o ai-kit não as traz. Last-verified: 2026-09-08.
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm de um projeto .NET em produção e o ai-kit não as traz. Last-verified: 2026-09-08.
 
 ---
 
@@ -201,7 +201,7 @@ A migração é um refactor que **não pode mudar o que o modelo lê**. Por isso
 
 ## Exemplos reais
 
-MORPH_GHLBrain, `src/Morph.GHLBrain/Features/Conversation/Operator/`:
+Um agente conversacional .NET em produção, na pasta da feature do operador:
 
 | Tool | Adaptador | `Ops` | Desfecho |
 |---|---|---|---|

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

@@ -0,0 +1,70 @@
+# Stack do Morph — a recomendação para projeto novo
+
+> **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, 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; catálogo de extensões do Neon lido em 2026-10-30. Last-verified: 2026-10-30.
+
+---
+
+## A stack
+
+Projeto novo começa nela **inteira** (`dotnet+nextjs --with neon`), mesmo quando a primeira feature caberia em menos: o projeto cresce, e a stack decidida no primeiro dia é a que carrega as regras certas. Recorte ou outra tecnologia é escolha explícita do usuário, nunca a recomendação. É a que os standards, as rules de domínio e o `stack-scan` conhecem.
+
+| Camada | Stack | Tag do `project.stack` |
+| --- | --- | --- |
+| Backend | .NET 10 + Vertical Slice (pasta por feature: handler + validator + endpoint + errors + tests) | `dotnet` |
+| ORM/DB | EF Core + Neon (Postgres) | `neon` em `project.integrations` |
+| Erros | Result pattern com `result.Match()` | — |
+| IA | Microsoft Agent Framework (MAF), quando houver agentes | `maf` em `project.integrations` |
+| Frontend | Next.js App Router + Tailwind + Motion + Shadcn | `nextjs` |
+| Jobs async | Hangfire, só com razão real | — |
+| Local | Docker Compose para as dependências, portas por variável | `docker` em `project.integrations` |
+
+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
+instala tudo o que ela carrega: rules de domínio em `.claude/rules/`, commands e skills filtrados pela stack. As rules só carregam no início de uma sessão do Claude Code: a sessão que implementa
+começa depois do `stack-set`.
+
+## Padrões proibidos
+
+Os standards detalham; o build, o lint e o `stack-scan` cobram o mecânico.
+
+- Exception como fluxo de controle: o Result põe o erro esperado no tipo.
+- Service/Manager entre o handler e os dados.
+- `IRepository<T>`/`IUnitOfWork`: o `DbSet<T>` já é o repository.
+- SQL cru sem ADR.
+- Redeclarar tipo que já existe: antes, `morph-spec graph explain <nome>` (sem grafo, `grep -rn`); criar exige `CRIAR` com `why` em `## Reuso`.
+
+## Fora da stack
+
+Outra tecnologia é decisão do usuário, registrada como ADR no plano (`**Alcance:** projeto`). O harness segue
+funcionando, mas sem rule de domínio para ela: as regras viram critério escrito no plano.

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,11 +5,12 @@
 > **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 (MORPH_GHLBrain, feature `catalogo-produtos-crud`, task T16,
-> 2026-07-13) hit the failure mode it documents. See [Known Failure Modes](#known-failure-modes-postmortem)
+> 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)
 > for the map from bug → section.
 
 ---
@@ -78,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
 
@@ -130,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;
 ```
@@ -138,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: {
@@ -733,8 +733,7 @@ Each Neon branch gets its own isolated auth data. This means:
 
 ## Known Failure Modes (Postmortem)
 
-Real bugs hit during the `catalogo-produtos-crud` end-to-end run (MORPH_GHLBrain, task T16,
-2026-07-13). Each one now has a permanent fix in this standard — this table exists so a review can
+Real bugs hit during an end-to-end run in a production project (2026-07-13). Each one now has a permanent fix in this standard — this table exists so a review can
 scan it in one pass instead of rediscovering these by trial and error.
 
 | # | Symptom | Root cause | Fixed in |

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -5,7 +5,7 @@
 > **Keywords:** image, gpt-image, gemini, openrouter, morph-assets, asset, ai-generation, placeholder, mcp, next/image
 > **Load When:** feature has UI components requiring image assets
 
-**Verified against:** morph-assets MCP (OpenRouter; default model `openai/gpt-image-2.5-flare`) + Next.js 15 `next/image`. Last-verified: 2026-09-27.
+**Verified against:** morph-assets MCP (OpenRouter; default model `openai/gpt-image-2.5-flare`) + Next.js 15 `next/image`. Last-verified: 2026-10-27.
 
 ---
 
@@ -88,6 +88,8 @@ mcp__morph-assets__list_models({ kind: "image", needs?: "refs>=5", task?: string
 
 **Cost gate:** every call estimates cost first. Above US$2, over the project budget or with an unknown price, the tool returns `CONFIRMATION_REQUIRED` + `confirmToken`; get human approval and repeat the same call with the token. Use `dryRun: true` before large batches or 4K.
 
+**Fallback:** when a model is unavailable the tool walks a curated fallback chain (same validation, at most 25 percent more expensive). `noFallback: true` turns it off when the exact model matters.
+
 ## Prompt Engineering Patterns
 
 ### Design-System-Aware Prompts
@@ -115,20 +117,47 @@ Describe what the image will BE in the UI, not just the subject:
 
 ### Narrative Style
 
-GPT Image, Gemini and MAI all respond best to coherent paragraphs. Build prompts by layering:
+GPT Image, Gemini and MAI all respond best to coherent paragraphs. Build prompts by layering, most important first:
+
+1. **Subject** — hyper-specific description. Not "a warrior in armor" but "a tall elven warrior in ornate silver plate armor with falcon-wing pauldrons and a high collar etched with leaf patterns".
+2. **Action / pose** — what the subject is doing, expression, gesture.
+3. **Environment** — foreground, mid-ground, background, described separately. A flat description ("neon city at night") gives a flat image; layers give depth.
+4. **Lighting** — the biggest quality lever. Multiple sources with different colors and directions: "golden hour key light from the left, cool blue fill from the sky on the right, warm rim light from behind catching the hair"; "harsh overhead spotlight with neon signs reflecting off wet surfaces"; "soft window light as primary, practical warm bulbs adding depth behind". A single flat source gives a flat image.
+5. **Style** — photography terms (camera, lens, film stock: "85mm portrait lens, shallow depth of field, Kodak Portra 400 grain"), a named illustration style ("cel-shaded", "watercolor", "ink wash", "art nouveau"), or a reference artist when useful ("in the style of Studio Ghibli").
+6. **Mood reference** — 1 or 2 real-world style references to anchor the look (a product film, an editorial).
+7. **Color palette** — dominant colors and contrast relationships ("warm amber highlights against deep teal shadows").
+8. **Composition** — camera angle, framing, negative space, and depth cues: overlapping objects, foreground blur, atmospheric perspective (distant objects fading into haze).
+9. **Texture and detail** — what makes it tactile: "rain droplets on glass", "worn leather with visible stitching", "dust in a light beam", "condensation on cold metal".
+
+Write it as a photo-direction paragraph, not as tags.
+
+**Never:** keyword spam ("beautiful, stunning, 4k, masterpiece"), JSON prompts (the models have no structured prompt mode), negative prompts ("no cars"). Describe what is there: "an empty, completely still street" rather than "a street without cars".
+
+### Category Templates
+
+Each kind of image has a skeleton that works. Fill the brackets with the layers above.
 
-1. **Subject** — hyper-specific description
-2. **Environment** — foreground, mid-ground, background (layered for depth)
-3. **Lighting** — multiple sources with different colors/directions
-4. **Style** — photography terms ("85mm portrait lens") or art style ("cel-shaded")
-5. **Color palette** — dominant colors and contrast relationships
-6. **Composition** — camera angle, framing, negative space
+| Category | Skeleton |
+|---|---|
+| Photorealistic | `A [shot type] of [subject with details], [action], set in [environment with atmosphere], illuminated by [lighting], captured with [camera/lens], [mood], [orientation].` |
+| Illustration / sticker | `[Art style] [subject with personality], [key details], [line style] outlines, [shading], [palette], [background].` |
+| Text rendering (logo, infographic, menu) | `[Image type] for [brand or concept context], featuring the text "[exact text]" in [font style], [elements around the text], [color scheme and style], [format].` |
+| Product mockup | `High-resolution studio photograph of [product with materials], on [surface], [lighting setup], [camera angle] for [purpose], sharp focus on [detail], [realism], [ratio].` |
+| Minimalist / negative space | `[Single subject] positioned [placement], [vast background], generous negative space [for what], [subtle light direction], [ratio].` |
+| Sequential art (comic, storyboard) | One generation per panel, same character description repeated verbatim in each. |
 
-**Never:** keyword spam ("beautiful, stunning, 4k, masterpiece"), JSON prompts, negative prompts ("no cars").
+Example (product mockup): "High-resolution studio photograph of a minimalist black ceramic mug with a matte finish on a polished concrete surface, three-point softbox lighting with a subtle warm key light, 45-degree elevated angle for an e-commerce listing, sharp focus on the steam rising from the coffee, photorealistic, square format."
+
+### Prompting Principles
+
+- **State the context and the intent.** "Logo for a high-end minimalist skincare brand" beats "make a logo": the model uses the context to make style decisions. Always say what the image is for (social post, site, print).
+- **One concept per generation.** Multi-scene compositions are unreliable. Generate the pieces separately and compose with editing.
+- **Character consistency.** If a character's features drift after several edits, start over with a detailed character description up front.
+- **Set the aspect ratio deliberately**, from the final use (see the guide below).
 
 ## Iterative Editing Workflows
 
-**Cardinal rule: generation demands depth; editing demands restraint.**
+**Cardinal rule: generation demands depth; editing demands restraint.** A verbose edit prompt makes the model re-imagine the whole image, and the result looks artificial and over-processed. Keep edits to one or two sentences about exactly what changes, and let the model integrate it. Editing keeps the aspect ratio of the input image; say so explicitly if you need a different one.
 
 ### Adding / Removing Elements
 One sentence. Don't describe how to integrate — the model handles that.
@@ -137,10 +166,11 @@ One sentence. Don't describe how to integrate — the model handles that.
 ```
 
 ### Background Replacement
-State the new background simply. Don't over-describe.
+State the new background simply. Don't over-describe: the model matches the lighting on its own.
 ```
 "Replace the background with a tropical beach at sunset."
 ```
+Over-described, and therefore more artificial, not less: "Replace the background with a beautiful tropical beach with golden sand, palm trees swaying, turquoise waves, warm sunset colors reflecting on the water, ensuring the subject's lighting matches the sunset glow".
 
 ### Inpainting (Targeted Changes)
 Name what changes and what stays in one line.
@@ -154,6 +184,13 @@ Name the target style.
 "Transform this into Van Gogh's Starry Night style."
 ```
 
+### Multi-Image Composition
+Pass the source images in `references` (paths, URLs, library ids, `@brand` / `@brand:name` with a `project`) and refer to them **by order** in the prompt:
+```
+"Put the woman from the second image in the blue dress from the first image."
+```
+The reference limit depends on the model (MAI Image Flash takes at most 5; 6 to 14 need Gemini 3.1 Flash Image). Check with `list_models { needs: "refs>=N" }` instead of assuming a fixed limit.
+
 ### Iterative Refinement with `continue_editing`
 One change at a time:
 - "Make the lighting warmer"
@@ -179,6 +216,8 @@ Put the exact copy between double quotes in the prompt (`the headline "Summer Sa
 | Story / reel | `9:16` | Mobile wallpaper, social story, vertical banner |
 | Standard display | `4:3` | Documentation, slides, standard display |
 
+**Cards follow the grid, not a fixed ratio.** `3:2` is the default for a landscape card in a row of feature cards or blog headers. Use portrait (`3:4` or `2:3`) when the card is a tall tile (a product or garment shown whole, a team member, a masonry gallery), and square (`1:1`) when the grid is uniform tiles or the same asset doubles as a social post. Generate at the ratio the card renders at, so the `object-fit: cover` crop does not cut the subject.
+
 ## File Naming & Directory
 
 **Convention:** `public/images/{feature}/{purpose}.png`
@@ -276,7 +315,7 @@ For a frame that will drive a scroll scrub, also generate at the exact ratio the
 
 ## The Two Assets Everyone Forgets
 
-- **Favicon / monogram.** Derive a simple mark (one or two letters, or the existing symbol) that reads at 32x32. Use `edit_image` from the real logo so it stays on-brand. Export PNG at 512x512 and let the browser downscale. **Never invent a new logo**, simplify the existing one.
+- **Favicon / monogram.** Derive a simple mark (one or two letters, or the existing symbol) that reads at 32x32. Use `edit_image` from the real logo so it stays on-brand. Export PNG at 512x512 and let the browser downscale, on a transparent background or a solid brand color, whichever the mark reads better on. **Never invent a new logo**, simplify the existing one.
 - **OG / share image (1200x630).** The image that appears when the link is pasted into a chat or a feed. Use the strongest shot on the page, with breathing room for a possible brand overlay. Generate or crop at that exact ratio. See `frontend/seo/meta-schema-audit.md`.
 
 ## Variations and Cost

package/framework/standards/frontend/design-system/ai-video-generation.md

@@ -5,7 +5,7 @@
 > **Keywords:** video generation, seedance, morph-assets, openrouter, img2vid, endImage, directional footage, loop video, E005 moderation, cost ladder, promoteFrom
 > **Load When:** producing footage for a scroll-driven page or animating a client render
 
-**Verified against:** morph-assets MCP (generate_video, generate_loop_video, get_video, library, media_tool) over OpenRouter; models `bytedance/seedance-1-5-pro` and `bytedance/seedance-2.0`. Last-verified: 2026-09-27.
+**Verified against:** morph-assets MCP (generate_video, generate_loop_video, get_video, library, media_tool) over OpenRouter; models `bytedance/seedance-1-5-pro` and `bytedance/seedance-2.0`. Last-verified: 2026-10-27.
 
 ---
 
@@ -38,7 +38,7 @@ Give a start image and an end image, and let the model interpolate a camera trav
 1. Pick or generate the **start frame**: the wide shot, the resting state.
 2. Pick or generate the **end frame** (`endImage`): the destination of the movement (a detail in close-up, a revealed facade).
 3. Call `generate_video { prompt, image: start, endImage: end }`. The prompt describes the camera movement between the two.
-4. Check the **last-frame QA** in the response (SSIM of the real last frame against `endImage`): ✅ respected, ⚠️ does not match, ≈ inconclusive. A ⚠️ means the model ignored `endImage` and the take will not scrub as designed.
+4. Check the **last-frame QA** in the response (SSIM of the real last frame against `endImage`): ✅ respected, ⚠️ does not match, ≈ inconclusive. A ⚠️ means the model ignored `endImage` and the take will not scrub as designed: adjust the prompt or the frames and regenerate before showing it to anyone. On ≈, decide by eye from the 6-frame preview the response carries.
 
 **Models that respect `endImage` (verified 2026-09-27):** Seedance 1.5 Pro and Seedance 2.0. Use them for scrub.
 
@@ -107,11 +107,55 @@ TECHNICAL: img2vid with image (start) + endImage (end). No audio. No watermark.
 
 ## Section 6: Async Contract
 
-`generate_video` and `generate_loop_video` wait up to `waitSeconds` (default 60) and, if the job is still running, return "⏳ generating" with the job id rather than a file. Poll with `get_video { ids? }` (several ids at once; no ids = every pending job), which downloads the `.mp4` once the job completes. **Never resend `generate_video` while a job is running**: an identical request within 15 minutes returns the same job, but a different one is billed again.
+`generate_video` and `generate_loop_video` wait up to `waitSeconds` and, if the job is still running, return "⏳ generating" with the job id rather than a file. **The default is 60s and the ceiling is 110s** (`DEFAULT_WAIT_S` / `MAX_WAIT_S` in the MCP's `src/tools/video.ts`). A Seedance job takes about 100 to 130s, so with the default it almost always comes back pending: pass `waitSeconds: 110` for Seedance, and even then expect to poll. Poll with `get_video { ids? }` (several ids at once; no ids = every pending job), which downloads the `.mp4` once the job completes. **Never resend `generate_video` while a job is running**: an identical request within 15 minutes returns the same job, but a different one is billed again.
 
 `library { op: "pending" | "list" | "info" }` reads local history and spends no credits (it replaces the old `list_videos`). `usage { op: "balance" }` checks the OpenRouter key without spending credits, which makes it the safe health check for the MCP.
 
-Post-production runs locally with no cost through `media_tool` (ffmpeg): `scrub_frames` (frames + `frames.json`, each re-extraction creates a new `v{N}` folder, which doubles as the cache-bust), `poster` (static image for mobile), `flip` (hflip when the subject collides with the copy), `concat`, `compress` (web background) and `picker` (the side-by-side approval page for the gate).
+Post-production runs locally with no cost through `media_tool` (ffmpeg): `scrub_frames` (frames + `frames.json`, each re-extraction creates a new `v{N}` folder, which doubles as the cache-bust), `poster` (static image for mobile), `flip` (hflip when the subject collides with the copy), `concat`, `compress` (web background) and `picker` (the side-by-side approval page for the gate). For an ambient loop, `compress { format: "webm", width: 1280 }` with no audio is usually enough: a test loop went from 421 KB to 52 KB (upstream `morph-lp-cinematic` skill; not re-measured here).
+
+---
+
+## Section 7: Seamless Loop Prompt (Ambient Plane)
+
+The special case from Section 1: a background video that plays itself on repeat, never the scroll-driven hero. Generate it with `generate_loop_video { prompt, image }`, which sends the same image as first and last frame. The prompt has to describe a complete cycle that returns to its start, and it has to be exhaustive about the details people leave vague: camera, lighting, timing, text and the loop point.
+
+**Infer the loop direction from the subject** when the brief does not give one:
+
+| Subject type | Default direction | Why |
+|---|---|---|
+| Mechanical, tech, electronics | Deconstruction reveal | shows engineering, internals, precision |
+| Vehicles, transportation | Motion flythrough or speed orbit | movement and power |
+| Fashion, wearables, accessories | Slow orbit focused on material and texture | craftsmanship and detail |
+| Food, beverage | Ingredient explosion or pour sequence | freshness, composition |
+| Abstract, software, SaaS | Particle morph or data visualization | makes the intangible visible |
+| Architecture, real estate | Cinematic flythrough or reveal | space and scale |
+| Beauty, skincare | Liquid or texture flow | sensory qualities |
+
+With the subject known, write the prompt; only a missing subject justifies a question, and one question is enough.
+
+**Seven sections, none skipped:**
+
+1. **SCENE.** The subject with material, color, form and key details ("matte black over-ear headphones with brushed aluminum hinges", never "headphones"); the environment around it (void, studio, abstract space); 1 or 2 real-world mood references (a product film, a director's style); the palette (background, accents, highlights).
+2. **CAMERA.** Motion type, speed, elevation, angle, distance, focal or depth-of-field notes. **Start position equals end position**: state the rotation in degrees ("one continuous 360-degree horizontal orbit at a fixed 15-degree elevation").
+3. **ACTION ARC.** The starting state; the transformation, granular and in order; the **peak** (maximum separation, closest zoom, most dramatic reveal) called out explicitly at roughly 40 to 60 percent of the duration; and the return, described as an intentional resolve ("components drift back and click into place"), not "it reverses". Slow build, peak, satisfying resolution.
+4. **TEXT CHOREOGRAPHY.** With headlines, for each one: the exact quoted string, the entrance relative to the action arc, position (upper third, center, lower third, aligned left or right), size (large and dominant), contrast (against the darkest or calmest region of the frame, with a darkening gradient or clear zone if the background is busy), exit, and entrance motion. Without headlines write exactly: "No text. No UI. Background plate only." **Readability wins**: if an effect hurts legibility, the effect yields.
+5. **LIGHTING & ATMOSPHERE.** Source, type (key, rim, ambient), color temperature, which edges the rim catches, atmospheric effects (particles, dust, bokeh). Lighting is **static** for the whole clip, with no shift, flicker or temperature change. Particle density and distribution are identical at the start and the end.
+6. **LOOP SEAL.** Same reference image for first and last frame; camera back at its exact start; every moving element (components, particles, effects) back in its starting state; no residual motion or lighting drift at the loop point; the return feels intentional (a click, a settle), never abrupt.
+7. **TECHNICAL.** Duration, seamless loop, image-to-video with the same first and last frame, no audio, no watermark. Resolution follows the cost ladder of Section 4 (the MCP renders 480p or 1080p, never 4K). **The duration in the prompt has to match the `duration` of the call**: the MCP defaults to 5s (`DEFAULT_DURATION` in `src/tools/video.ts`), so a prompt choreographed for 10s and sent without `duration: 10` comes out compressed into 5s, peak and text included. The accepted durations come from the OpenRouter catalog per model (`list_models` shows them; Seedance 2.0 takes 4 to 15s), and an out-of-range value is snapped to the nearest one with a warning.
+
+**Craft rules.** Specificity over vagueness: exact angles, speeds, degrees and percentages. Describe what happens on screen, never editing software ("the frame scales inward rapidly", not "apply a keyframed scale in After Effects"). Direct, technical tone, like a director's shot notes, with no hype words ("stunning", "breathtaking", "mesmerizing"). Bullets inside each section for scanability.
+
+A short, neutral example of the level of detail expected (a background plate with no text):
+
+```
+SCENE: a brushed-steel wristwatch with a sapphire crystal floats in a deep charcoal void; sparse silver dust drifts behind it. Mood: macro product film, precision-engineering reveal. Palette: charcoal background, cool steel, one warm amber highlight on the crown.
+CAMERA: one continuous 360-degree horizontal orbit at a fixed 10-degree elevation, slow and unhurried, 85mm macro feel, shallow depth of field. Ends at its exact starting angle and distance.
+ACTION ARC: the watch at rest; the case back opens and the movement lifts out in layers; peak at 50% with every layer separated; the layers settle back and the case closes with a soft click.
+TEXT CHOREOGRAPHY: No text. No UI. Background plate only.
+LIGHTING & ATMOSPHERE: cool key light from the upper left, thin warm rim on the right edge, static for the whole clip; dust density identical at start and end.
+LOOP SEAL: same reference image as first and last frame; camera, layers and dust back to their starting state; no residual motion at the loop point.
+TECHNICAL: 10s seamless loop, image-to-video with identical first and last frame, no audio, no watermark.
+```
 
 ---
 
@@ -126,6 +170,8 @@ Post-production runs locally with no cost through `media_tool` (ffmpeg): `scrub_
 - [ ] Prompt reserves a calm region for copy, subject opposite the text
 - [ ] Draft at 480p approved before any 1080p render, and the final made with `promoteFrom`
 - [ ] Frames re-extracted with a bumped cache-bust after the final render
+- [ ] Seedance calls made with `waitSeconds: 110`; a pending job polled with `get_video`, never resent
+- [ ] Ambient loop prompt carries all seven sections, static lighting and an explicit loop seal, and the call passes the same `duration` the prompt was written for
 
 ## Boundary: Runtime Generation Is Another Standard
 

package/framework/standards/frontend/design-system/art-direction.md

@@ -15,7 +15,7 @@ A design that follows the tokens, has every state and passes WCAG can still be f
 
 ## Section 1: Write the Direction First
 
-Before the first component, answer four questions in `1-design/direcao.md`:
+Before the first component, answer four questions; the chosen direction goes in `**Direção escolhida:**` of `1-design/mockups.md`:
 
 1. **Concept in one sentence.** What the screen says, not what it contains. *"The login tells the product cycle in scenes while you sign in."*
 2. **Visual metaphor.** The image that organizes the layout. *Stories; a control room; a ticket being stamped; a garden that grows.*
@@ -80,7 +80,7 @@ The direction is proved in a rendered prototype, not in prose: `1-design/prototi
 
 ## Checklist
 
-- [ ] `direcao.md` answers concept, metaphor, memorable, must-not-look-like
+- [ ] The direction answers concept, metaphor, memorable, must-not-look-like
 - [ ] Two or three distinct directions for a new screen or brand moment, one recommended with a reason
 - [ ] Fewer than three template tells on the final screen
 - [ ] Mobile composed at 390 px on its own terms

package/framework/standards/frontend/scroll-driven/frame-scrub.md

@@ -5,7 +5,7 @@
 > **Keywords:** frame-scrub, canvas, scroll-driven video, scrubbing, ffmpeg, apple-style, poster fallback
 > **Load When:** ui-designer active, or the brief says scroll controls a video
 
-**Verified against:** GSAP 3.13 ScrollTrigger + Lenis 1.x + ffmpeg 6.x, shipped to production. Last-verified: 2026-08-21.
+**Verified against:** GSAP 3.13 ScrollTrigger + Lenis 1.x + ffmpeg 6.x, shipped to production. Last-verified: 2026-10-27.
 
 ---
 
@@ -51,7 +51,17 @@ const framePath = (i) => `/hero-frames/v${manifest.version}/frame_${String(i).pa
 
 Source: the upstream `morph-lp-cinematic` skill (build-stack reference); not re-measured here.
 
-**Treat total sequence weight as a performance budget.** It shows up directly in Lighthouse. If it is too heavy, cut frame count (120 instead of 145) or resolution before cutting quality.
+**Footage from an AI video model is 24 fps, not 30.** A 4s Seedance clip comes out with about 97 frames, which already sits in the useful range: 100 to 145 frames scrubs smoothly without getting heavy. Keep the source frame rate unless the sequence is too light to scrub smoothly. In the upstream test, 97 WebP frames at 1080p weighed about 2 MB in total; `scrub_frames` warns above 25 MB, which is too heavy for a hero. Source: the upstream `morph-lp-cinematic` skill; not re-measured here.
+
+**Treat total sequence weight as a performance budget.** It shows up directly in Lighthouse. If it is too heavy, cut frame count (120 instead of 145), width (1280) or quality before cutting the sequence length.
+
+**Manual WebP extraction that matches the manifest layout.** When `scrub_frames` is unavailable, extract into the same `v{N}/frame_%04d` structure so the manifest-driven `framePath` above keeps resolving:
+
+```bash
+ffmpeg -i hero.mp4 -vf "fps=24,scale=1920:-1" -c:v libwebp -quality 80 v1/frame_%04d.webp
+```
+
+Prepend `hflip,` to the `-vf` chain to mirror, and bump the folder (`v2/`, `v3/`) on every re-extraction.
 
 **Mirror the footage when the subject collides with the copy.** If the subject sits on the side where text goes, flip it during extraction: