@polymorphism-tech/morph-spec 9.7.0 → 10.0.0

package/framework/standards/STANDARDS.json

@@ -1164,9 +1164,12 @@
         "brand-fidelity": "#brand-fidelity-reference-dont-invent",
         "to-video": "#downstream-images-that-become-video",
         "favicon-og": "#the-two-assets-everyone-forgets",
-        "variations": "#variations-and-cost"
+        "variations": "#variations-and-cost",
+        "templates": "#category-templates",
+        "principles": "#prompting-principles",
+        "multi-image": "#multi-image-composition"
       },
-      "digest": "Guidelines for generating project images with the morph-assets MCP (OpenRouter; default openai/gpt-image-2.5-flare, drafts on mai-image-2.6-flash, gemini-3.1-flash-image for 2K/4K or 6-14 refs; models: [...] compares): when to use AI versus stock versus SVG, prompt patterns, aspect ratios, iterative editing and assets.md format. Core principle is brand fidelity over invention: always pass the client's real assets as references (or @brand with a project) via edit_image rather than generating in a vacuum, never AI-recreate a property developer's architectural render or a physical product (animate or reference the real one), and chain derivatives from an approved hero so the whole set shares light, palette and identity. Frame anything destined to become video WITHOUT a face, because video moderation is stricter (E005), and generate scrub frames at the video's exact ratio with the subject opposite the copy. Always produce the two forgotten assets: a favicon derived from the real logo (never a new one) and a 1200x630 OG share image. Offer two to three genuinely different variations per image (variants returns a contact sheet), varying angle, light or composition since seed is not supported by the GPT Image/Gemini models, and never advance with a weak image because every derivative inherits it. Copy to render goes between double quotes; CONFIRMATION_REQUIRED needs human approval and a confirmToken."
+      "digest": "Guidelines for generating project images with the morph-assets MCP (OpenRouter; default openai/gpt-image-2.5-flare, drafts on mai-image-2.6-flash, gemini-3.1-flash-image for 2K/4K or 6-14 refs; models: [...] compares): when to use AI versus stock versus SVG, prompt patterns, aspect ratios, iterative editing and assets.md format. Core principle is brand fidelity over invention: always pass the client's real assets as references (or @brand with a project) via edit_image rather than generating in a vacuum, never AI-recreate a property developer's architectural render or a physical product (animate or reference the real one), and chain derivatives from an approved hero so the whole set shares light, palette and identity. Frame anything destined to become video WITHOUT a face, because video moderation is stricter (E005), and generate scrub frames at the video's exact ratio with the subject opposite the copy. Always produce the two forgotten assets: a favicon derived from the real logo (never a new one) and a 1200x630 OG share image. Offer two to three genuinely different variations per image (variants returns a contact sheet), varying angle, light or composition since seed is not supported by the GPT Image/Gemini models, and never advance with a weak image because every derivative inherits it. Copy to render goes between double quotes; CONFIRMATION_REQUIRED needs human approval and a confirmToken. Prompts are a layered photo-direction paragraph (subject, action, environment in foreground/mid/background, multi-source lighting, style, mood reference, palette, composition with depth cues, texture), with a skeleton per category (photorealistic, illustration, text rendering, product mockup, minimalist); edits stay one or two sentences and keep the input ratio."
     },
     {
       "id": "frontend-design-system-ai-video-generation",
@@ -1190,9 +1193,11 @@
         "directional": "#section-2-building-directional-footage",
         "moderation": "#section-3-faces-trip-moderation",
         "cost-ladder": "#section-4-the-cost-ladder",
-        "prompt-skeleton": "#section-5-prompt-skeleton"
+        "prompt-skeleton": "#section-5-prompt-skeleton",
+        "async": "#section-6-async-contract",
+        "loop-prompt": "#section-7-seamless-loop-prompt-ambient-plane"
       },
-      "digest": "The decisive rule: a perfect loop has an end frame identical to its start, which is right for a self-playing ambient background and WRONG for scroll scrubbing, because start and end look the same and the page reads as frozen while the user scrolls. Scroll-driven footage needs directional movement via generate_video with an endImage (push-in/dolly is the most reliable, then reveal, pull-back, slow tilt); avoid orbits and any movement that returns to its origin. Client architectural renders are animated with img2vid, never AI-recreated. Human faces repeatedly trip moderation (E005), so crop the face out of frame (neck down, hands, product) and reserve faces for static image generation. Always climb the cost ladder: seedance-1-5-pro 480p draft to judge framing and movement, then promoteFrom to seedance-2.0 1080p only after approval (same prompt, frames and seed), then re-extract frames with a bumped cache-bust. seedance-2.0-mini does NOT respect endImage and Veo 3.1 Lite/Fast are inconclusive, so scrub only on Seedance 1.5 Pro/2.0 and check the last-frame SSIM QA. Video has no ZDR on OpenRouter: nothing sensitive in the frames. Prompts read like director notes with no hype words, and must reserve a calm dark region for the page copy with the subject on the opposite side. Generation is async via the morph-assets MCP (OpenRouter): a running job is polled with get_video (several ids at once), never by resending generate_video; library reads local history and spends no credits; media_tool extracts scrub frames and posters."
+      "digest": "The decisive rule: a perfect loop has an end frame identical to its start, which is right for a self-playing ambient background and WRONG for scroll scrubbing, because start and end look the same and the page reads as frozen while the user scrolls. Scroll-driven footage needs directional movement via generate_video with an endImage (push-in/dolly is the most reliable, then reveal, pull-back, slow tilt); avoid orbits and any movement that returns to its origin. Client architectural renders are animated with img2vid, never AI-recreated. Human faces repeatedly trip moderation (E005), so crop the face out of frame (neck down, hands, product) and reserve faces for static image generation. Always climb the cost ladder: seedance-1-5-pro 480p draft to judge framing and movement, then promoteFrom to seedance-2.0 1080p only after approval (same prompt, frames and seed), then re-extract frames with a bumped cache-bust. seedance-2.0-mini does NOT respect endImage and Veo 3.1 Lite/Fast are inconclusive, so scrub only on Seedance 1.5 Pro/2.0 and check the last-frame SSIM QA. Video has no ZDR on OpenRouter: nothing sensitive in the frames. Prompts read like director notes with no hype words, and must reserve a calm dark region for the page copy with the subject on the opposite side. Generation is async via the morph-assets MCP (OpenRouter): a running job is polled with get_video (several ids at once), never by resending generate_video; library reads local history and spends no credits; media_tool extracts scrub frames and posters. waitSeconds defaults to 60 with a 110 ceiling while a Seedance job takes about 100-130s, so pass 110 and still expect to poll. An ambient loop prompt has seven mandatory sections (scene, camera returning to its start, action arc with a mid peak, text choreography or 'background plate only', static lighting, loop seal, technical), with the loop direction inferred from the subject type."
     },
     {
       "id": "frontend-design-system-animations",
@@ -1860,7 +1865,7 @@
         "motion": "#section-6-motion-with-intent",
         "prototype": "#section-7-prototype-and-self-review"
       },
-      "digest": "Order beats talent: before any component of a new or changed screen, write 1-design/direcao.md with the concept in one sentence, the visual metaphor, what makes it memorable, and what it must NOT look like. New screens and brand moments (login, onboarding, first screen, empty state, success) explore 2-3 DISTINCT directions and recommend one with a product reason. Avoid template tells (raw shadcn look, white card centered on gray, generic icon list, default fonts, flat backgrounds, mobile as stacked desktop, decorative fade-ins, made-up numbers); three or more means raise it. Mobile is composed at 390px on its own (bottom sheet, thumb zone, 44px targets). Motion tells something with the lightest tool (CSS keyframes > scroll-driven CSS > Framer Motion > GSAP), transform/opacity only, and a composed reduced-motion version. Prove it in 1-design/prototipos/{screen}.html with the project REAL tokens, screenshotted at 1280 and 390 and revised until it passes."
+      "digest": "Order beats talent: before any component of a new or changed screen, write the direction (Direção escolhida in 1-design/mockups.md) with the concept in one sentence, the visual metaphor, what makes it memorable, and what it must NOT look like. New screens and brand moments (login, onboarding, first screen, empty state, success) explore 2-3 DISTINCT directions and recommend one with a product reason. Avoid template tells (raw shadcn look, white card centered on gray, generic icon list, default fonts, flat backgrounds, mobile as stacked desktop, decorative fade-ins, made-up numbers); three or more means raise it. Mobile is composed at 390px on its own (bottom sheet, thumb zone, 44px targets). Motion tells something with the lightest tool (CSS keyframes > scroll-driven CSS > Framer Motion > GSAP), transform/opacity only, and a composed reduced-motion version. Prove it in 1-design/prototipos/{screen}.html with the project REAL tokens, screenshotted at 1280 and 390 and revised until it passes."
     },
     {
       "id": "architecture-engineering-lens",
@@ -1930,6 +1935,28 @@
         "not-a-rule": "#o-que-não-é-regra"
       },
       "digest": "Rules with a reason that a machine can see are lint errors, not prose: one eslint.config.mjs at the Next app root, flat config spreading eslint-config-next/core-web-vitals and eslint-config-next/typescript, no new plugin. ESLint 9 (eslint-plugin-import/react peer range; the bundled typescript-eslint wants TypeScript <6.1); Next 16 next build no longer lints; the verify build node runs eslint --quiet on the files the feature changed (legacy lint debt never reddens a feature), from the app root, when eslint.config.* and eslint are present. no-restricted-imports bans framer-motion (one import path, motion/react), zustand/redux/@reduxjs/toolkit (server state is TanStack Query, page and filters in the URL), DB drivers pg/@neondatabase/serverless/@prisma/client/drizzle-orm/postgres (Next never touches the database; the .NET API does), the legacy shadcn @/components/ui/form, and @/features/*/* deep imports outside src/features (use the feature index.ts). import/no-restricted-paths: src/components never imports src/features, src/features never imports src/app, src/hooks never imports the API client (lib/api-client.ts, lib/api). no-restricted-syntax: fetch or apiClient called inside useEffect, and 'use client' in the root app/layout.tsx. import/no-default-export except Next convention files (page, layout, loading, error, not-found, template, default, route, sitemap, robots, icons, OG images) and *.config.*. @typescript-eslint/no-explicit-any error, no-console warn. A new restriction is one line in this file with the reason in its message; a one-off exception is eslint-disable-next-line with the reason. CSS class naming, animation class catalogs, optional className, Zod on props, motion counts and offsets, QueryClient defaults and prop-drilling depth are taste: neither prose nor lint."
+    },
+    {
+      "id": "architecture-stack-baseline",
+      "name": "stack baseline",
+      "path": "architecture/stack-baseline.md",
+      "category": "architecture",
+      "subcategory": null,
+      "tags": [
+        "architecture",
+        "stack",
+        "greenfield"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "anchors": {
+        "stack": "#a-stack",
+        "declare": "#declarar",
+        "forbidden": "#padrões-proibidos",
+        "outside": "#fora-da-stack"
+      },
+      "digest": "Projeto novo começa na stack do Morph INTEIRA (dotnet+nextjs --with neon), mesmo que a primeira feature caiba em menos; recorte ou outra tecnologia só por escolha explícita do usuário:.NET 10 + Vertical Slice (handler + validator + endpoint + errors + tests), EF Core + Neon (Postgres), Result pattern com result.Match(), Microsoft Agent Framework quando houver agentes, Next.js App Router + Tailwind + Motion + Shadcn, Hangfire só com razão real, Docker Compose para as dependências locais. Tags: project.stack dotnet|nextjs|dotnet+nextjs; integrations neon, maf, docker. Declare com `morph-spec stack-set <stack> --with <integrações>`, que grava o config.json e instala as rules de domínio; as rules só carregam no início de uma sessão, então a sessão que implementa começa depois. Proibido: exception como fluxo, Service/Manager entre handler e dados, IRepository/IUnitOfWork, SQL cru sem ADR, redeclarar tipo existente. Outra tecnologia é ADR de projeto no plano, sem rule de domínio."
     }
   ]
 }

package/framework/standards/STANDARDS.meta.json

@@ -1196,7 +1196,7 @@
         "refactor neutro",
         "migracao de teste"
       ],
-      "verifiedAgainst": "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.",
+      "verifiedAgainst": "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.",
       "provedBy": []
     },
     "frontend-design-system-art-direction": {
@@ -1253,6 +1253,10 @@
       ],
       "verifiedAgainst": "eslint 9.39.5, eslint-config-next 16.4.2 (typescript-eslint 8.71.2, eslint-plugin-import 2.32.0), next 16.4.2, typescript 6.0.3 (sonda: um arquivo ruim por regra → erro da regra esperada, `no-console` → aviso, arquivos conformes e o scaffold `morph-spec scaffold nextjs` → 0 problemas).",
       "provedBy": []
+    },
+    "architecture-stack-baseline": {
+      "verifiedAgainst": ".NET 10, EF Core 10, Next.js 16 App Router, Microsoft Agent Framework 1.0.",
+      "provedBy": []
     }
   },
   "sharedAliases": {

package/framework/standards/ai-agents/agent-session.md

@@ -21,12 +21,11 @@
 | O histórico é **só** a lista de mensagens, sem campo próprio, e o projeto não precisa lê-lo fora do agente | `AgentSession` + um `ChatHistoryProvider` embutido |
 | Protótipo, CLI, demo, teste | `InMemoryChatHistoryProvider` |
 
-**O veredito da casa: conversa própria como default.** Isso não é preferência — é a aplicação do critério acima aos projetos que existem. GHLBrain, MORPH_OS e ProspectPRO caem todos nas três primeiras linhas.
+**O veredito da casa: conversa própria como default.** Isso não é preferência — é a aplicação do critério acima aos projetos que existem. Os três agentes da casa em produção caem todos nas três primeiras linhas.
 
 ### Os três fundamentos, cada um citável
 
-1. **ADR D3 do GHLBrain.** O estado da conversa vive em `conv_checkpoints`; `ToolAgentRunner.cs:126-130` roda *"sem AgentThread/sessão"* — porque o **retry depende de o histórico ser visível e manipulável**: para repetir uma volta que falhou é preciso remontar as mensagens, e não dá para remontar o que está dentro de um objeto opaco. Registrado em `docs/specs/elevacao-9/brutos/scan-ghlbrain.md:58` e `:599`.
-2. **Doc oficial de self-hosting** (learn.microsoft.com/en-us/agent-framework/hosting/self-hosting/, `ms.date` 2026-08-17), verbatim: *"MAF doesn't include a general-purpose durable session store"*. Produção exige implementação própria. A mesma página recomenda, em conversa longa, um `ChatHistoryProvider` externo **com mensagens por linha** em vez de reescrever a sessão inteira a cada turno.
+1. **Decisão de arquitetura de um agente .NET em produção.** O estado da conversa vive em `conv_checkpoints`; o runner roda *"sem AgentThread/sessão"* — porque o **retry depende de o histórico ser visível e manipulável**: para repetir uma volta que falhou é preciso remontar as mensagens, e não dá para remontar o que está dentro de um objeto opaco.2. **Doc oficial de self-hosting** (learn.microsoft.com/en-us/agent-framework/hosting/self-hosting/, `ms.date` 2026-08-17), verbatim: *"MAF doesn't include a general-purpose durable session store"*. Produção exige implementação própria. A mesma página recomenda, em conversa longa, um `ChatHistoryProvider` externo **com mensagens por linha** em vez de reescrever a sessão inteira a cada turno.
 3. **Padrão do canal** (Rasmus, parte 06 — "Conversations"): objeto de conversa próprio do domínio, com **um** mapper para `ChatMessage`. A conversa é entidade de negócio; o formato do provedor é detalhe de transporte.
 
 ### Ligação com a Responses API

package/framework/standards/ai-agents/context-providers.md

@@ -23,7 +23,7 @@ Preciso que o agente saiba X.
                                                       (nem provider, nem tool)
 ```
 
-**O caso concreto que a regra evita:** RAG passivo injetado como context provider. O usuário digita "oi" e o agente paga uma busca vetorial + o custo dos trechos no prompt — **em todo turno**, inclusive nos que não precisam de conhecimento nenhum. Como tool, o "oi" não dispara busca alguma. Foi medido em produção: o escopo institucional da base do GHLBrain roda sem `LIMIT`, e passivo isso é custo por turno, não por necessidade.
+**O caso concreto que a regra evita:** RAG passivo injetado como context provider. O usuário digita "oi" e o agente paga uma busca vetorial + o custo dos trechos no prompt — **em todo turno**, inclusive nos que não precisam de conhecimento nenhum. Como tool, o "oi" não dispara busca alguma. Foi medido em produção: o escopo institucional de uma base de conhecimento roda sem `LIMIT`, e passivo isso é custo por turno, não por necessidade.
 
 ### O compositor determinístico — a alternativa que não é provider
 
@@ -45,7 +45,7 @@ var plan = PlanFor(conversation.Stage);
 var options = new ChatOptions { Instructions = plan.Instructions, Tools = [.. plan.Tools] };
 ```
 
-É a prática do GHLBrain (`OperatorPlan`) e o padrão do canal: **o código decide o modo, o LLM classifica**. Um provider que "sugere" quais tools usar deixa a decisão com o modelo; a allow-list tira a decisão do modelo.
+É a prática de um agente em produção (um plano do operador decidido em código) e o padrão do canal: **o código decide o modo, o LLM classifica**. Um provider que "sugere" quais tools usar deixa a decisão com o modelo; a allow-list tira a decisão do modelo.
 
 ---
 

package/framework/standards/ai-agents/durable-workflows-hitl.md

@@ -71,7 +71,7 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 | **Um agente**, uma tool de efeito irreversível (cobrar, enviar proposta, apagar) | `ApprovalRequiredAIFunction` — **sem workflow nenhum** |
 | Um grafo com etapa humana entre executores, ou espera de dias | `RequestPort` + `CheckpointManager` |
 
-O caso do agente único é o que a casa realmente tem (MORPH_OS: billing, envio de proposta) e é o que faltava neste standard.
+O caso do agente único é o que a casa realmente tem (billing, envio de proposta) e é o que faltava neste standard.
 
 ### O ciclo, medido em `Microsoft.Extensions.AI` 10.9.0
 
@@ -271,7 +271,7 @@ This framework deploys to VPS/Coolify by default and does not adopt Azure as a d
 - Human-in-the-loop (HITL) | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/human-in-the-loop
 - Checkpoints | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints
 - Durable Extension | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/integrations/durable-extension
-- Release notes 1.14 (2026-07-21) e 1.17 do `microsoft/agent-framework` — graduação do `ToolApprovalAgent` e extração do Durable Task (compilados em `docs/specs/elevacao-9/brutos/research-maf.md:312-331`, lidos 2026-09-07)
+- Release notes 1.14 (2026-07-21) e 1.17 do `microsoft/agent-framework` — graduação do `ToolApprovalAgent` e extração do Durable Task (lidos 2026-09-07)
 
 ---
 

package/framework/standards/ai-agents/providers/model-registry.md

@@ -114,7 +114,7 @@ Read it narrowly, because it **is** narrow: the restriction needs **four** facts
 
 ### Origin 2 — measured in the field, no primary source
 
-*"Reasoning models reject `temperature != 1` when tools are present."* This is **measured in production**, not documented: GHLBrain's `ToolAgentRunner.cs:35-38` strips temperature for that path, recorded in `docs/specs/elevacao-9/brutos/scan-ghlbrain.md:106`, and corroborated by third parties (issues on `openai-python` and LibreChat). **The 2026-09-08 research did not find a primary OpenAI sentence stating it.**
+*"Reasoning models reject `temperature != 1` when tools are present."* This is **measured in production**, not documented: a production .NET agent strips temperature for that path, and this is corroborated by third parties (issues on `openai-python` and LibreChat). **The 2026-09-08 research did not find a primary OpenAI sentence stating it.**
 
 So it lives in the schema as a **per-alias flag with mandatory provenance** (`constraints.temperatureUnsupported` + `constraints.provenance`), never as a universal rule hardcoded in the registry. Whoever turns it on is asserting it for one specific model and writing where they got it from.
 
@@ -187,7 +187,7 @@ Going through `Microsoft.Extensions.AI` (`IChatClient`) or the MAF (`AIAgent`) k
 
 > **Restore trap, measured 2026-09-08:** `Microsoft.Extensions.AI.OpenAI` 10.9.0 declares `OpenAI (>= 2.12.0 && < 2.13.0)`. Pairing it with the pinned `OpenAI` 2.13.0 emits **NU1608** on restore. Either pin `OpenAI` to 2.12.x alongside the bridge, or accept the warning knowingly and write the decision in `plan.md` (`## Decisões`). Do not discover this in CI.
 
-**No floating ranges.** Every `PackageReference` above is an exact version. A floating `2.*` on a weekly-cadence SDK is how ProspectPRO bought a `MissingMethodException` on the Responses API **after paying for the call** (`docs/specs/elevacao-9/brutos/scan-prospectpro.md:55`).
+**No floating ranges.** Every `PackageReference` above is an exact version. A floating `2.*` on a weekly-cadence SDK is how a production project bought a `MissingMethodException` on the Responses API **after paying for the call**.
 
 **Adding a provider branch:** the `ModelRegistry.cs` template implements `openai` + `ollama`. To add `google`, `anthropic`, or `azure-openai`:
 1. Confirm the current NuGet SDK — community SDKs evolve; check NuGet/context7 before coding.

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.
 
 ---
 
@@ -340,4 +340,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,47 @@
+# 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
+> **Load When:** escolhendo a stack de um projeto novo, ou julgando um desvio de stack no plano
+
+**Verified against:** .NET 10, EF Core 10, Next.js 16 App Router, Microsoft Agent Framework 1.0. Last-verified: 2026-10-27.
+
+---
+
+## 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`).
+
+## 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/integrations/neon-auth/neon-auth.md

@@ -8,8 +8,7 @@
 **Verified against:** Neon Auth — @neondatabase/auth + @neondatabase/auth-ui (Better Auth). Last-verified: 2026-07-13.
 
 > 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.
 
 ---
@@ -733,8 +732,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: