@polymorphism-tech/morph-spec 8.40.0 → 8.42.0

package/framework/skills/core/morph-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.40.0"
+cliVersion: "8.42.0"
 ---
 
 # morph-uiux
@@ -32,7 +32,7 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
    - **Sistemas, não telas isoladas** — mesmo critério da persona `ui-designer`: componentes reutilizáveis antes de composições de uso único.
    - **Toda tela sai com o checklist de tela preenchido** (template no passo 3) — a superfície, o volume esperado de dados, paginação, ordenação, filtro, os três estados (vazio, carregando, erro), o comportamento no mobile e abas × página longa. "Não se aplica" vale, **desde que escrito**. É o checklist que faz a lista de 2 000 linhas paginar: o que o design não decide não vira `doneCriteria` (`morph-plan` §5d), e o que não é critério ninguém entrega. Tela de dados segue os standards de `admin-app` (lista/tabela, formulário, feedback, estrutura de página), que a persona cita na superfície `admin-app`.
 
-3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem o escopo das implementadoras (com Bash) + `Skill` + MCPs `stitch`/`gemini-image`/`playwright`/`context7`/`seedance`/`graphify`. Bash serve para `morph-spec standards --find`, `npx`, screenshot e leitura de `git`; build/test da suíte, `verify` e aprovação de gate continuam do orquestrador (cláusula 3, como nas outras personas).
+3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem o escopo das implementadoras (com Bash) + `Skill` + MCPs `stitch`/`playwright`/`context7`/`graphify` + o MCP de mídia morph-assets (imagem e vídeo). Bash serve para `morph-spec standards --find`, `npx`, screenshot e leitura de `git`; build/test da suíte, `verify` e aprovação de gate continuam do orquestrador (cláusula 3, como nas outras personas).
 
    **Persona universal** (`ui-designer.stack = ["*"]` em `agents.json`, mesmo mecanismo de `evaluator`/`scout`): UI/UX importa sempre que há superfície de UI, então o subagent está registrado em **todo** projeto — .NET/Blazor incluído, não só Next.js. **Fallback** (caso raro: instalação anterior a essa mudança, `.claude/agents/morph-ui-designer.md` ainda não regenerado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório — resolvido rodando `morph-spec setup-infra --reinstall`.
 
@@ -46,7 +46,7 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
    Produza, NESTA ORDEM — design-system.md primeiro, os demais só como aplicável ao escopo:
    1. `design-system.md` — tokens (cor, tipografia, espaço, motion) consistentes com o projeto
    2. `mockups.md` — descrição estruturada de cada tela nova/alterada (+ imagem via MCP
-      gemini-image/stitch quando disponível; fallback: descrição textual detalhada).
+      stitch ou o MCP de mídia (imagem/vídeo) quando disponível; fallback: descrição textual detalhada).
       Cada tela é um `## Tela: <nome>` e traz, dentro dela, o checklist abaixo, com cada `…`
       trocado pela decisão — "não se aplica" vale se escrito; `…`, vazio ou "a definir" não.
       O que cada item decide: Superfície (admin-app | marketing-site — ela escolhe que

package/framework/standards/PROVENANCE.json

@@ -38,13 +38,13 @@
       "skills": []
     },
     {
-      "id": "gemini-image",
+      "id": "morph-image",
       "repo": "morph-HUB",
-      "path": "skills/gemini-image",
+      "path": "skills/morph-image",
       "envVar": "MORPH_HUB",
       "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "ec0abd827badfd5cd6d4c5f8b1843f81a3d183fe",
-      "sourceCommit": "b6bbfff",
+      "sourceTree": "e55dcf307278583120601c3c5d55118302335f7b",
+      "sourceCommit": "c4c9164",
       "distilledOn": "2026-09-09",
       "distilledFrom": [
         "SKILL.md"

package/framework/standards/STANDARDS.json

@@ -1551,7 +1551,7 @@
         "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code",
         "test-budget": "#test-budget"
       },
-      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior (edge cases included) are rows of one [Theory], never copied [Fact]s; no test whose only assertion is a copy, config or prose string (that is an analyzer or a publish-time validation, outside the suite count); shared fixtures before new helpers; TDD for bugs (regression first) and pure logic; a surviving mutant is killed by tightening an assertion or adding a row, not by a new test.",
+      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior (edge cases included) are rows of one [Theory], never copied [Fact]s; no test whose only assertion is a copy, config or prose string (that is an analyzer or a publish-time validation, outside the suite count); shared fixtures before new helpers; bugs and pure logic get tests in any order — the implementer runs its own filter once, never red-green cycles nor production mutation (the Gate 3 mutation proof shows the test bites); a surviving mutant is killed by tightening an assertion or adding a row, not by a new test.",
       "verifiedAgainst": ".NET 10 + xUnit 2 + `Microsoft.Extensions.TimeProvider.Testing`.",
       "provedBy": []
     },
@@ -1850,8 +1850,8 @@
         "favicon-og": "#the-two-assets-everyone-forgets",
         "variations": "#variations-and-cost"
       },
-      "digest": "Guidelines for generating project images with the Gemini Image MCP: 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 referenceImages 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, varying angle, light or composition rather than the seed, and never advance with a weak image because every derivative inherits it.",
-      "verifiedAgainst": "Gemini Image MCP + Next.js 15 `next/image`.",
+      "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.",
+      "verifiedAgainst": "morph-assets MCP (OpenRouter; default model `openai/gpt-image-2.5-flare`) + Next.js 15 `next/image`.",
       "provedBy": []
     },
     {
@@ -1889,8 +1889,8 @@
         "cost-ladder": "#section-4-the-cost-ladder",
         "prompt-skeleton": "#section-5-prompt-skeleton"
       },
-      "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: fast/480p/4s draft to judge framing and movement, 1080p only after approval, then re-extract frames with a bumped cache-bust. 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: generate_video returns a request_id polled via get_video; list_videos reads local history and spends no credits.",
-      "verifiedAgainst": "seedance MCP (generate_video, generate_loop_video, get_video, list_videos) over Replicate.",
+      "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.",
+      "verifiedAgainst": "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`.",
       "provedBy": []
     },
     {
@@ -2371,7 +2371,7 @@
         "e2e": "#test-file-co-location",
         "test-budget": "#test-budget"
       },
-      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior are rows of one it.each, never copied it() blocks; no test whose only assertion is a copy string (lint or publish-time validation instead); shared wrappers, MSW handlers and factories before new helpers; TDD for bugs and pure logic, component tests may come after the code.",
+      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior are rows of one it.each, never copied it() blocks; no test whose only assertion is a copy string (lint or publish-time validation instead); shared wrappers, MSW handlers and factories before new helpers; bugs and pure logic get tests in any order — the implementer runs its own filter once, never red-green cycles nor production mutation.",
       "verifiedAgainst": "Vitest 3 + React Testing Library 16 + MSW 2.",
       "provedBy": []
     },
@@ -2848,7 +2848,7 @@
         "not-worth": "#o-que-não-merece",
         "size": "#tamanho"
       },
-      "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and decisions.md), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. The verify validators node (code-budget) warns on added comments that cite process and on added comment density.",
+      "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and decisions.md; in a test the link to the postcondition goes in the test NAME), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. A heavily commented neighbour file is not a model. The comment-guard hook blocks an edit that ADDS process history, a banner/#region, a block over 3 lines or a doc-comment outside a published package; the verify validators node (code-budget) warns on added comments that cite process and on added comment density.",
       "verifiedAgainst": "C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo).",
       "provedBy": []
     }

package/framework/standards/architecture/code-comments.md

@@ -43,7 +43,8 @@ Só o **porquê que o código não mostra**:
 
 - **História de processo.** Task, UC, ADR, FR, Gate, avaliador, `spec.md`, mockup, "confirmado ao
   implementar a T11", "o Gate 3 pediu". Isso vai na mensagem de commit e no `decisions.md`, onde tem
-  data e autor e não envelhece dentro do arquivo.
+  data e autor e não envelhece dentro do arquivo. Em teste, o elo com a pós-condição vai no **nome**
+  do teste (`P5_estado_do_lead_espelha_o_crm`, `DisplayName`), nunca em `// UC-672 P5`.
 - **Repetição do código.** `// incrementa o contador` sobre `count++`, `// valida o request` sobre
   `validator.Validate(request)`. Nome bom substitui comentário.
 - **Doc-comment que repete a assinatura.** `/// <summary>Obtém o pedido.</summary>` sobre
@@ -63,7 +64,8 @@ Só o **porquê que o código não mostra**:
 Uma linha é o normal; teto de ~3. Acima disso o comentário justifica o volume (algoritmo não
 óbvio, armadilha de terceiro com a reprodução). Bloco longo narrando decisões é `decisions.md` com
 outro nome. Em volume, código de aplicação fica perto de zero: mais de uma linha de comentário a
-cada dez de código é sinal de que os nomes não estão fazendo o trabalho.
+cada dez de código é sinal de que os nomes não estão fazendo o trabalho. Arquivo vizinho muito
+comentado não é modelo: código novo segue este padrão, não a densidade do legado.
 
 ## Exemplo
 
@@ -90,6 +92,11 @@ await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
 
 ## Na revisão
 
+Na hora da edição, o hook `comment-guard` bloqueia o comentário **adicionado** que é história de
+processo, banner/`#region`, bloco de mais de 3 linhas ou `///`/JSDoc em projeto que não é pacote
+publicado. Comentário que o arquivo já tinha nunca é acusado. Repetir o código em uma linha não é
+detectável por forma: fica com a revisão abaixo.
+
 Comentário que o código dispensava é achado da rubrica `code-quality` no Gate 3. O nó `validators`
 do `morph-spec verify` mede, nas linhas que a feature adicionou (validador `code-budget`), quantas
 linhas de comentário citam processo e a densidade de comentário sobre o código adicionado, e avisa

package/framework/standards/backend/dotnet/testing.md

@@ -128,8 +128,10 @@ regression test per bug fixed**. Going above it takes a one-line justification i
 - **Shared fixture by default.** Reuse the project's `WebApplicationFactory` fixture, fakes and
   builders. Before writing a new helper, look for the existing one (`morph-spec graph explain
   <Name>`; fallback without a graph: `grep -rn`).
-- **TDD where it pays:** a bug gets its regression test first (red, then the fix), and so does pure
-  logic. Integration and endpoint tests may come after the code.
+- **Order is free, proof is not the implementer's:** a bug gets a regression test, and pure logic
+  gets its tests, in whatever order the code comes out. The implementer does not run red→green
+  cycles nor mutate production code to watch a test fail; it runs its own filter once before the
+  report, and the Gate 3 mutation proof is what shows the test bites.
 - **A surviving mutant** of the Gate 3 mutation proof is killed by tightening an existing assertion
   or adding a table row, not by one new test per mutant.
 

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

@@ -2,10 +2,10 @@
 
 > **Scope:** nextjs
 > **Layer:** 1 (load when relevant)
-> **Keywords:** image, gemini, asset, ai-generation, placeholder, mcp, next/image
+> **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:** Gemini Image MCP + Next.js 15 `next/image`. Last-verified: 2026-05-20.
+**Verified against:** morph-assets MCP (OpenRouter; default model `openai/gpt-image-2.5-flare`) + Next.js 15 `next/image`. Last-verified: 2026-09-27.
 
 ---
 
@@ -13,7 +13,7 @@
 
 | Use Case | Approach | Examples |
 |----------|----------|---------|
-| **AI generation** | Gemini Image MCP | Hero images, brand illustrations, feature-specific visuals, empty states, background panels |
+| **AI generation** | morph-assets MCP | Hero images, brand illustrations, feature-specific visuals, empty states, background panels |
 | **Stock photos** | External sources | Generic content (people in offices, nature scenes, stock portraits) |
 | **SVG/CSS** | Code-based | Icons, patterns, gradients, geometric shapes, loading animations |
 | **Skip** | Other tools | Screenshots (Playwright), diagrams (Mermaid), logos (vector tools) |
@@ -22,7 +22,7 @@
 
 ## Brand Fidelity: Reference, Don't Invent
 
-The advantage of an image MCP over generating from scratch is staying consistent with the client's **real** assets. Pass them as reference (`edit_image` with `referenceImages`) rather than generating in a vacuum. A generated look-alike is a different product, and the client sees it immediately.
+The advantage of an image MCP over generating from scratch is staying consistent with the client's **real** assets. Pass them as reference (`edit_image` / `references`, or `@brand` with a `project`) rather than generating in a vacuum. A generated look-alike is a different product, and the client sees it immediately.
 
 Two cases where this is a hard rule:
 
@@ -34,46 +34,60 @@ Two cases where this is a hard rule:
 Generate the **hero first**. Once approved, use it as the reference for every derived image (detail shots, cards, scene variants), so the whole set shares light, palette and identity instead of looking like separate photo shoots.
 
 ```
-hero -> [approved] -> derivatives with the approved hero as referenceImages -> [approved per image]
+hero -> [approved] -> derivatives with the approved hero as references -> [approved per image]
 ```
 
 Skipping this chain is the most common cause of a page whose images do not feel like one set.
 
-## Gemini Image MCP API
+## morph-assets MCP API
+
+One MCP for image and video, all models through OpenRouter. `model` accepts any OpenRouter image model by id, alias (`flare`, `mai flash`, `nano banana 2`, `nano banana pro`) or approximate name.
+
+| Role | Model |
+|------|-------|
+| Default (editing with refs, text) | `openai/gpt-image-2.5-flare` |
+| Draft | `microsoft/mai-image-2.6-flash` (max 5 refs) |
+| 2K/4K output or 6-14 references | `google/gemini-3.1-flash-image` |
 
 ```javascript
 // Generate a new image
-mcp__gemini-image-mcp__generate_image({
-  prompt: string,           // Text description (max 5000 chars, narrative style)
+mcp__morph-assets__generate_image({
+  prompt: string,           // Narrative description; copy to render goes between double quotes
+  model?: string,           // Default: openai/gpt-image-2.5-flare
+  models?: string[],        // 2-4 models: same request in each, cost per model (to choose)
   aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "9:16" | "16:9",
+  resolution?: "1K" | "2K" | "4K", // Only on models that support it
+  variants?: number,        // 1-4, returns a contact sheet for the review
+  references?: string[],    // Paths, URLs, library ids, "@brand", "@brand:name"
+  project?: string,         // Client project: output dir, brand refs, budget
   outputPath?: string,      // File path to save (e.g., "public/images/feature/hero.png")
-  model?: string,           // Default: gemini-2.5-flash-image
+  dryRun?: boolean,         // Estimate cost only
+  confirmToken?: string,    // Repeat a CONFIRMATION_REQUIRED call after approval
 })
 
-// Edit an existing image
-mcp__gemini-image-mcp__edit_image({
-  imageSource: string,      // Path to image or image ID
+// Edit an existing image (the base image goes as the 1st reference)
+mcp__morph-assets__edit_image({
+  image: string,            // Path to image or library id
   prompt: string,           // Short, targeted edit instructions (1-2 sentences)
+  references?: string[],
   outputPath?: string,
 })
 
-// Continue editing last image
-mcp__gemini-image-mcp__continue_editing({
+// Continue editing the last image of the project
+mcp__morph-assets__continue_editing({
   prompt: string,           // One adjustment at a time
+  imageId?: string,         // Default: the last image
 })
 
-// List generated images
-mcp__gemini-image-mcp__list_images({
-  type?: "generated" | "edited" | "all",
-  limit?: number,
-})
+// History and metadata (replaces list_images / get_image_info)
+mcp__morph-assets__library({ op: "list" | "search" | "info" | "tag" | "project_get" | "project_set", ... })
 
-// Get image details
-mcp__gemini-image-mcp__get_image_info({
-  imageId?: string,         // Defaults to last image
-})
+// Pick a model from the curation (verified vs broken)
+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.
+
 ## Prompt Engineering Patterns
 
 ### Design-System-Aware Prompts
@@ -101,7 +115,7 @@ Describe what the image will BE in the UI, not just the subject:
 
 ### Narrative Style
 
-Gemini responds best to coherent paragraphs. Build prompts by layering:
+GPT Image, Gemini and MAI all respond best to coherent paragraphs. Build prompts by layering:
 
 1. **Subject** — hyper-specific description
 2. **Environment** — foreground, mid-ground, background (layered for depth)
@@ -148,9 +162,9 @@ One change at a time:
 - "More serious expression"
 
 ### Text Rendering
-The model frequently misspells words. After generating any image with text:
+Put the exact copy between double quotes in the prompt (`the headline "Summer Sale"`) so the model renders it literally; GPT Image (the default) is the strongest at text. Models can still misspell words. After generating any image with text:
 1. View the result
-2. If text is wrong: `continue_editing` with "Fix the text — it should read '{correct text}' exactly. Keep everything else."
+2. If text is wrong: `continue_editing` with "Fix the text — it should read "{correct text}" exactly. Keep everything else."
 3. Expect 2-3 iterations for correct text
 
 ## Aspect Ratio Guide
@@ -267,7 +281,7 @@ For a frame that will drive a scroll scrub, also generate at the exact ratio the
 
 ## Variations and Cost
 
-Generate **two or three variations per image**, varying angle, light or composition, **not just the seed**. Seed-only variation produces near-identical options and wastes the review.
+Generate **two or three variations per image** (`variants: 2-3` returns a contact sheet for the review), varying angle, light or composition. Seed is not supported by the GPT Image / Gemini models, so variation has to come from the prompt; near-identical options waste the review. To choose between models or directions, `models: [...]` runs the same request on 2-4 models with the cost of each.
 
 If none are good, regenerate at the same step with the prompt adjusted by the feedback. **Do not advance with a weak image**: every derivative, any footage built from it, and the final page all inherit its quality.
 
@@ -282,7 +296,7 @@ If none are good, regenerate at the same step with the prompt adjusted by the fe
 - [ ] `priority` prop set for above-the-fold images
 - [ ] Build compiles after integration (`npm run build`)
 - [ ] Image visible in dev server at correct route
-- [ ] Client assets passed as `referenceImages`; nothing generated in a vacuum
+- [ ] Client assets passed as `references` (or `@brand`); nothing generated in a vacuum
 - [ ] Real renders and real product photos used as-is, never AI-recreated
 - [ ] Hero approved first, then used as reference for derivatives
 - [ ] Images headed for video framed without faces

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

@@ -2,10 +2,10 @@
 
 > **Scope:** frontend-design-system
 > **Layer:** 3
-> **Keywords:** video generation, seedance, img2vid, endImage, directional footage, loop video, E005 moderation, cost ladder
+> **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:** seedance MCP (generate_video, generate_loop_video, get_video, list_videos) over Replicate. Last-verified: 2026-08-21.
+**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.
 
 ---
 
@@ -38,6 +38,13 @@ 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.
+
+**Models that respect `endImage` (verified 2026-09-27):** Seedance 1.5 Pro and Seedance 2.0. Use them for scrub.
+
+- `seedance-2.0-mini` does **not** respect `endImage` (it overshoots the end frame). Do not use it for scrub.
+- Veo 3.1 Lite/Fast came out **inconclusive** on the last-frame check. Do not rely on them for scrub until re-verified.
+- `aspectRatio: "adaptive"` does not exist on OpenRouter: omit `aspectRatio` to inherit the ratio of the start frame.
 
 **Movements that scrub well:**
 
@@ -52,11 +59,12 @@ Give a start image and an end image, and let the model interpolate a camera trav
 
 ## Section 3: Faces Trip Moderation
 
-Img2vid with a **human face** repeatedly fails moderation (error E005). The workaround that works is to **crop the face out of frame** before generating.
+Img2vid with a **human face** repeatedly fails moderation (it surfaced as error E005 on Replicate and still trips moderation through OpenRouter). The workaround that works is to **crop the face out of frame** before generating.
 
 - Frame from the neck down (garment, hands, fabric) rather than the whole person. For tailoring, craft and manufacturing this usually improves the shot, because the product becomes the subject.
 - Hands working (at a cuff, a button, the material) pass reliably and carry the craft story.
 - If the client insists on a face, generate the **static image** with it (image generation is more permissive) and reserve video for the face-free shots.
+- **Video has no ZDR (zero data retention) on OpenRouter:** the provider may retain the frames. Nothing sensitive in them (documents, screens with client data, identifiable people).
 
 ---
 
@@ -64,8 +72,10 @@ Img2vid with a **human face** repeatedly fails moderation (error E005). The work
 
 Every generation costs money and you rarely nail the movement on the first attempt.
 
-1. **Draft:** fast model, 480p, 4s. Enough to judge framing and movement.
-2. **Final:** only after the draft is approved, regenerate at 1080p. Then re-extract frames and swap them into the build **with a cache-bust** (`?v=N`), or the browser serves the old ones. See `frontend/scroll-driven/frame-scrub.md`.
+1. **Draft:** the default model (`bytedance/seedance-1-5-pro`), 480p (the default), 4-5s. About US$0.05 per take; enough to judge framing and movement. Ambient loops can stay on this model.
+2. **Final:** only after the draft is approved, promote it: `generate_video { promoteFrom: "<draft id>", model: "seedance", resolution: "1080p" }` renders `bytedance/seedance-2.0` at 1080p with the **same prompt, frames and seed** (about US$1.50 for 4s). Then re-extract frames and swap them into the build **with a cache-bust** (`?v=N`), or the browser serves the old ones. See `frontend/scroll-driven/frame-scrub.md`.
+
+To choose between models before drafting, `models: ["a", "b"]` runs the same request on 2-3 models with the cost of each. Any generation above US$2, over the project budget or with an unknown price returns `CONFIRMATION_REQUIRED` + `confirmToken`: get human approval, then repeat the same call with the token. `dryRun: true` only estimates.
 
 Never open at 1080p.
 
@@ -95,7 +105,11 @@ TECHNICAL: img2vid with image (start) + endImage (end). No audio. No watermark.
 
 ## Section 6: Async Contract
 
-`generate_video` and `generate_loop_video` return a `request_id` rather than a file. Poll with `get_video { requestId, outputPath? }`, which downloads the `.mp4` once the job reports COMPLETED. `list_videos { limit? }` reads local job history and spends no credits, which also makes it the safe health check for the MCP.
+`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.
+
+`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).
 
 ---
 
@@ -104,15 +118,16 @@ TECHNICAL: img2vid with image (start) + endImage (end). No audio. No watermark.
 - [ ] Directional footage (start differs from end) for anything scroll-driven
 - [ ] Seamless loop used only for a self-playing ambient plane
 - [ ] Client renders animated, never AI-recreated
-- [ ] Faces cropped out of frame before img2vid
+- [ ] Faces cropped out of frame before img2vid; nothing sensitive in the frames (no ZDR)
+- [ ] Scrub footage generated on a model that respects `endImage` (Seedance 1.5 Pro / 2.0, never `seedance-2.0-mini`) and the last-frame QA came back ✅
 - [ ] Movement chosen from the scrub-friendly list, no orbits or returns
 - [ ] Prompt reserves a calm region for copy, subject opposite the text
-- [ ] Draft at 480p/4s approved before any 1080p render
+- [ ] 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
 
 ## Boundary: Runtime Generation Is Another Standard
 
-This standard is **authoring time**: a human driving the seedance MCP in a session, footage that ends
+This standard is **authoring time**: a human driving the morph-assets MCP in a session, footage that ends
 up committed as a page asset. When the **product itself** generates video at runtime — a .NET worker
 creating a paid task, polling an operation, downloading bytes into its own blob store — the standard
 is `ai-agents/media-video.md` (Veo via `Google.GenAI`, the HTTP-only providers, cost per second, the

package/framework/standards/frontend/nextjs/testing.md

@@ -116,8 +116,10 @@ happy path + one error path per component above is that budget applied to a comp
 - **Shared helpers by default.** Reuse the existing wrappers (`test/helpers.tsx`), MSW handlers and
   factories. Before writing a new one, look for it (`morph-spec graph explain <Name>`; fallback
   without a graph: `grep -rn`).
-- **TDD where it pays:** a bug gets its regression test first, and so does pure logic (formatters,
-  reducers, schema). Component and integration tests may come after the code.
+- **Order is free, proof is not the implementer's:** a bug gets a regression test, and pure logic
+  (formatters, reducers, schema) gets its tests, in whatever order the code comes out. The
+  implementer does not run red→green cycles nor mutate production code to watch a test fail; it
+  runs its own filter once before the report, and the Gate 3 mutation proof shows the test bites.
 
 ## Common Mistakes
 

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

@@ -80,37 +80,44 @@ const docs = await mcp__context7__query-docs({
 
 Fallback: WebSearch for component documentation, WebFetch for specific component API pages.
 
-### Gemini Image MCP — AI Image Generation
+### morph-assets MCP — AI Image and Video Generation
 
 > Available in: **UI/UX** (preview generation), **Implement** (production assets)
 
+One MCP for image, video and local post-production, all models through OpenRouter. Default image model `openai/gpt-image-2.5-flare`; default video model `bytedance/seedance-1-5-pro` (draft/loop), final `bytedance/seedance-2.0` 1080p via `promoteFrom`. `model` accepts any OpenRouter model by id or alias; `models: [...]` compares the same request across models.
+
 | Tool | Use Case | Example |
 |------|----------|---------|
-| `generate_image` | Create new image from text prompt | `mcp__gemini-image-mcp__generate_image({ prompt, aspectRatio, outputPath })` |
-| `edit_image` | Modify existing image | `mcp__gemini-image-mcp__edit_image({ imageSource, prompt })` |
-| `continue_editing` | Iterate on last generated/edited image | `mcp__gemini-image-mcp__continue_editing({ prompt })` |
-| `list_images` | Browse image generation history | `mcp__gemini-image-mcp__list_images({ type: "all" })` |
-| `get_image_info` | Get metadata about a specific image | `mcp__gemini-image-mcp__get_image_info({ imageId })` |
+| `generate_image` | Create new image from text prompt | `mcp__morph-assets__generate_image({ prompt, aspectRatio, outputPath })` |
+| `edit_image` | Modify existing image | `mcp__morph-assets__edit_image({ image, prompt, references })` |
+| `continue_editing` | Iterate on last generated/edited image | `mcp__morph-assets__continue_editing({ prompt })` |
+| `generate_video` / `generate_loop_video` | Directional footage (`image` + `endImage`) / ambient loop | `mcp__morph-assets__generate_video({ prompt, image, endImage })` |
+| `get_video` | Poll one or more video jobs (never resend `generate_video`) | `mcp__morph-assets__get_video({ ids })` |
+| `media_tool` | ffmpeg post-production: scrub frames, poster, concat, compress, approval picker | `mcp__morph-assets__media_tool({ op: "scrub_frames", input })` |
+| `library` | History and metadata (replaces `list_images` / `get_image_info` / `list_videos`) | `mcp__morph-assets__library({ op: "list" })` |
+| `list_models` / `usage` | Pick a model from the curation / spend and credit balance | `mcp__morph-assets__usage({ op: "balance" })` |
 
 Read `design-system.md` first to get the project colors and aesthetic direction. Keep edits short and targeted, and iterate with `continue_editing` one change at a time.
 
 ```javascript
-const image = await mcp__gemini-image-mcp__generate_image({
+const image = await mcp__morph-assets__generate_image({
   prompt: "A floating tablet showing a modern dashboard interface on a dark charcoal background with copper and gold accent lighting. Premium luxury aesthetic, photorealistic, cinematic lighting with warm rim light.",
   aspectRatio: "16:9",
   outputPath: "public/images/my-feature/hero-mockup.png"
 });
 
-await mcp__gemini-image-mcp__edit_image({
-  imageSource: "public/images/my-feature/hero-mockup.png",
+await mcp__morph-assets__edit_image({
+  image: "public/images/my-feature/hero-mockup.png",
   prompt: "Make the lighting warmer and add a subtle copper glow around the tablet edges."
 });
 
-await mcp__gemini-image-mcp__continue_editing({
+await mcp__morph-assets__continue_editing({
   prompt: "More contrast in the shadows."
 });
 ```
 
+Paid per generation: above US$2, over the project budget or with an unknown price the tool returns `CONFIRMATION_REQUIRED` + `confirmToken` (get human approval, then repeat the same call with the token); `dryRun: true` only estimates.
+
 Fallback: manual image creation, stock photos, or placeholder divs.
 
 **Use cases by phase:**
@@ -121,7 +128,7 @@ Fallback: manual image creation, stock photos, or placeholder divs.
 | Implement (7) | Generate production assets from assets.md specs | `generate_image` + `edit_image` |
 | Implement (7) | Iterate on generated images for quality | `continue_editing` |
 
-> **Standard:** See `frontend/design-system/ai-image-generation.md` for prompt engineering patterns, aspect ratio guide, and `assets.md` format.
+> **Standard:** See `frontend/design-system/ai-image-generation.md` for prompt engineering patterns, aspect ratio guide, and `assets.md` format, and `frontend/design-system/ai-video-generation.md` for directional footage and the video cost ladder.
 
 ---
 
@@ -271,7 +278,7 @@ PRs/issues: sempre `gh` CLI (Bash). Deployments fallback: `vercel` CLI.
 | Container ops | Docker CLI (`docker ps`, `docker logs`, `docker compose`) | — |
 | Cloud resources | Azure CLI (`az resource`, `az deployment`) | — |
 | Vercel deployments | Vercel MCP | Bash `vercel` CLI |
-| AI image generation | Gemini Image MCP | Manual creation or stock photos |
+| AI image and video generation | morph-assets MCP | Manual creation or stock photos |
 
 **Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not. **Exceptions:** Neon, Docker, Azure **and GitHub** always use their respective CLIs directly — never MCP (`gh` já retorna JSON estruturado via `--json`, sem Docker nem PAT em env var).
 

package/package.json

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

package/src/commands/project/doctor.js

@@ -16,7 +16,7 @@ import {
   getInstalledCLIVersion
 } from '../../utils/version-checker.js';
 import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
-import { checkMissingAgents, checkAgentsDrift, maxTurnsError, surfacesError } from '../../utils/agents-installer.js';
+import { checkMissingAgents, checkAgentsDrift, maxTurnsError, surfacesError, effortError } from '../../utils/agents-installer.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { auditGraph } from '../../lib/graph/graph-health.js';
 import { auditFeatureLifecycle } from '../../core/state/lifecycle-audit.js';
@@ -208,6 +208,14 @@ export function validateAgentsJson(agentsData) {
     ? { name: 'agents.json surfaces', status: 'error', msg: surfacesErrors.join(' | ') }
     : { name: 'agents.json surfaces', status: 'ok' });
 
+  // 6: effort — same installer rule, same severity.
+  const effortErrors = agentEntries
+    .map(([id, data]) => effortError(id, data?.effort))
+    .filter(Boolean);
+  checks.push(effortErrors.length > 0
+    ? { name: 'agents.json effort', status: 'error', msg: effortErrors.join(' | ') }
+    : { name: 'agents.json effort', status: 'ok' });
+
   if (missingV5Fields.length > 0 && isV5) {
     const sample = missingV5Fields.slice(0, 3).join(', ');
     checks.push({