@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

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

@@ -125,16 +125,19 @@ real sign-in attempt, not after debugging a mysterious "session never sticks" bu
 
 ### SDK Initialization
 
+`lib/auth/client.ts` — `createAuthClient` takes the public auth URL as a positional argument, and the
+React hooks are re-exported from the client instance for ergonomic imports:
+
 ```typescript
-// lib/auth/client.ts
 'use client';
 import { createAuthClient } from '@neondatabase/auth/next';
-// createAuthClient takes the public auth URL as a positional argument
 export const authClient = createAuthClient(process.env.NEXT_PUBLIC_AUTH_URL!);
-// Re-export the React hooks from the client instance for ergonomic imports
 export const { useSession } = authClient;
+```
+
+`lib/auth/server.ts`:
 
-// lib/auth/server.ts
+```typescript
 import { createNeonAuth } from '@neondatabase/auth/next/server';
 export const auth = createNeonAuth({
   baseUrl: process.env.NEON_AUTH_BASE_URL!,
@@ -152,8 +155,9 @@ Import the Tailwind styles for the UI components in `globals.css`:
 @import '@neondatabase/auth-ui/tailwind';
 ```
 
+`app/providers.tsx`:
+
 ```tsx
-// app/providers.tsx
 'use client';
 import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
 import { authClient } from '@/lib/auth/client';
@@ -169,8 +173,9 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 ### Auth API Route
 
+`app/api/auth/[...path]/route.ts`:
+
 ```typescript
-// app/api/auth/[...path]/route.ts
 import { auth } from '@/lib/auth/server';
 
 export const { GET, POST } = auth.handler();
@@ -182,8 +187,9 @@ export const { GET, POST } = auth.handler();
 
 ### Sign In / Sign Up Pages
 
+`app/auth/sign-in/page.tsx`:
+
 ```tsx
-// app/auth/sign-in/page.tsx
 import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignInPage() {
@@ -193,8 +199,11 @@ export default function SignInPage() {
     </div>
   );
 }
+```
+
+`app/auth/sign-up/page.tsx`:
 
-// app/auth/sign-up/page.tsx
+```tsx
 import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignUpPage() {
@@ -208,8 +217,9 @@ export default function SignUpPage() {
 
 ### Server-Side Auth Check
 
+`app/dashboard/page.tsx`:
+
 ```typescript
-// app/dashboard/page.tsx
 import { auth } from '@/lib/auth/server';
 import { redirect } from 'next/navigation';
 
@@ -228,8 +238,9 @@ export default async function DashboardPage() {
 
 ### Client Component with User Data
 
+`components/UserProfile.tsx`:
+
 ```tsx
-// components/UserProfile.tsx
 'use client';
 import { useSession } from '@/lib/auth/client';
 
@@ -249,14 +260,15 @@ export function UserProfile() {
 
 ### Route Protection (Middleware)
 
+`middleware.ts`. The `runtime = 'nodejs'` line is **mandatory** for any `middleware.ts` that touches
+Neon Auth: Next.js middleware runs on the Edge runtime by default, and the network call the Neon Auth
+SDK makes to mint the session-data cookie times out inside the Edge sandbox on `next dev` — the request
+silently bounces back to sign-in even with a fully valid session, with no error surfaced.
+
 ```typescript
-// middleware.ts
 import { auth } from '@/lib/auth/server';
 
-// MANDATORY for any middleware.ts that touches Neon Auth. Next.js middleware runs on the Edge
-// runtime by default, and the network call the Neon Auth SDK makes to mint the session-data cookie
-// times out inside the Edge sandbox on `next dev` — the request silently bounces back to sign-in
-// even with a fully valid session, with no error surfaced. Force the Node.js runtime instead.
+// Mandatory: on the Edge runtime the SDK's session-cookie call times out and silently bounces to sign-in.
 export const runtime = 'nodejs';
 
 export default auth.middleware({
@@ -294,7 +306,6 @@ export default function ProtectedPage() {
 ## OAuth (Social Login)
 
 ```typescript
-// Trigger OAuth sign-in
 await authClient.signIn.social({
   provider: 'google',
   callbackURL: 'http://localhost:3000/auth/callback',
@@ -307,8 +318,9 @@ Configure OAuth providers in the Neon Console under Auth > Configuration.
 
 ## API Route Protection
 
+`app/api/protected/route.ts`:
+
 ```typescript
-// app/api/protected/route.ts
 import { auth } from '@/lib/auth/server';
 
 export const dynamic = 'force-dynamic';
@@ -348,34 +360,38 @@ backend's real prefix and the proxy's public prefix don't happen to match charac
 because this is a runtime routing mismatch (404, or the proxy calling itself), it **never shows up at
 build time**, only when a human clicks the page.
 
+`lib/api/prefixes.ts` — `BACKEND_API_PREFIX` is used ONLY by Server Components / Route Handlers
+calling the .NET backend directly (e.g. `https://api.example.com`; the backend's own routes have NO
+`/api` prefix); `PROXY_API_PREFIX` is used ONLY by Client Components calling the same-origin Next.js
+proxy, and matches `app/api/proxy/[...path]/route.ts`:
+
 ```typescript
-// lib/api/prefixes.ts
-// BACKEND_API_PREFIX: used ONLY by Server Components / Route Handlers calling the .NET backend directly.
-export const BACKEND_API_PREFIX = process.env.API_URL; // e.g. https://api.example.com — backend's own routes have NO /api prefix
+export const BACKEND_API_PREFIX = process.env.API_URL;
 
-// PROXY_API_PREFIX: used ONLY by Client Components calling the same-origin Next.js proxy.
-export const PROXY_API_PREFIX = '/api/proxy'; // matches app/api/proxy/[...path]/route.ts
+export const PROXY_API_PREFIX = '/api/proxy';
 ```
 
+The two call sites below — `app/(dashboard)/catalog/page.tsx`, a Server Component calling the backend
+directly, and `features/catalog/hooks/use-items.ts`, a Client Component going through the same-origin
+proxy — MUST resolve to the same backend route:
+
 ```typescript
-// app/(dashboard)/catalog/page.tsx — Server Component, direct backend call
 import { BACKEND_API_PREFIX } from '@/lib/api/prefixes';
 
 async function getItems() {
-  // cross-reference: PROXY_API_PREFIX below MUST resolve to the same backend route
   const res = await fetch(`${BACKEND_API_PREFIX}/catalog/items`, { next: { revalidate: 60 } });
   return res.json();
 }
 ```
 
+`features/catalog/hooks/use-items.ts`:
+
 ```typescript
-// features/catalog/hooks/use-items.ts — Client Component, via same-origin proxy
 import { PROXY_API_PREFIX } from '@/lib/api/prefixes';
 
 export function useItems() {
   return useQuery({
     queryKey: ['catalog', 'items'],
-    // cross-reference: BACKEND_API_PREFIX above MUST resolve to the same backend route
     queryFn: async () => (await fetch(`${PROXY_API_PREFIX}/catalog/items`)).json(),
   });
 }
@@ -435,31 +451,30 @@ Before marking any task that adds or touches an endpoint as done:
 
 ### JWT Bearer Configuration
 
+`Infrastructure/Auth/NeonAuthOptions.cs` — `BaseUrl` is the Neon Auth Base URL, e.g.
+`https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth`:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthOptions.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 public sealed class NeonAuthOptions
 {
     public const string SectionName = "NeonAuth";
 
-    /// <summary>Neon Auth Base URL, e.g. https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth</summary>
     public string BaseUrl { get; set; } = string.Empty;
 }
 ```
 
+`Infrastructure/Auth/NeonAuthJwksProvider.cs` fetches and caches Neon Auth's raw JWKS
+(`/.well-known/jwks.json` — there is no OIDC discovery document) for 15 minutes; an unknown `kid`
+forces one refresh, to survive key rotation without waiting out the TTL:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthJwksProvider.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 using Microsoft.Extensions.Options;
 using Microsoft.IdentityModel.Tokens;
 
-/// <summary>
-/// Fetches and caches Neon Auth's raw JWKS (/.well-known/jwks.json — there is no OIDC discovery
-/// document). Cached for 15 minutes; a forced refresh happens once when an unknown `kid` is seen,
-/// to survive key rotation without waiting out the TTL.
-/// </summary>
 public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAuthOptions> options)
 {
     private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(15);
@@ -473,7 +488,7 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
         var key = keySet.Keys.FirstOrDefault(k => k.Kid == kid);
         if (key is not null) return key;
 
-        // Unknown kid — could be key rotation. Force a single refresh before giving up.
+        // Unknown kid may be key rotation: refresh once before giving up.
         keySet = await GetKeySetAsync(forceRefresh: true, cancellationToken);
         return keySet.Keys.FirstOrDefault(k => k.Kid == kid);
     }
@@ -503,8 +518,9 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
 }
 ```
 
+`Infrastructure/Auth/NeonAuthServiceExtensions.cs`:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthServiceExtensions.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 using System.Text;
@@ -527,9 +543,7 @@ public static class NeonAuthServiceExtensions
         services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
             .AddJwtBearer(options =>
             {
-                // Do NOT set options.Authority — Neon Auth serves no /.well-known/openid-configuration,
-                // so Authority-driven metadata refresh has nothing valid to fetch. ValidIssuer is set
-                // explicitly below instead.
+                // No options.Authority: Neon Auth serves no OIDC discovery document, so ValidIssuer is explicit.
                 options.TokenValidationParameters = new TokenValidationParameters
                 {
                     ValidateIssuer = true,
@@ -537,14 +551,12 @@ public static class NeonAuthServiceExtensions
                     ValidateAudience = false,
                     ValidateLifetime = true,
                     NameClaimType = "sub",
-                    // Trust in the signing key is established entirely inside SignatureValidator
-                    // below (fetched from our own cached JWKS) — this flag doesn't gate that path.
+                    // Key trust is established inside SignatureValidator below; this flag doesn't gate that path.
                     ValidateIssuerSigningKey = false,
                 };
             });
 
-        // A second Configure<TDep> pass with DI available — AddJwtBearer's own setup has already run,
-        // so this only *adds* the SignatureValidator to the TokenValidationParameters built above.
+        // Runs after AddJwtBearer's own setup, with DI available: it only adds the SignatureValidator.
         services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
             .Configure<NeonAuthJwksProvider>((options, jwks) =>
             {
@@ -561,9 +573,7 @@ public static class NeonAuthServiceExtensions
                     if (string.IsNullOrEmpty(kid))
                         throw new SecurityTokenInvalidSignatureException("Token is missing 'kid'.");
 
-                    // Blocking call: JWKS is cached in-memory (see NeonAuthJwksProvider), so this is
-                    // I/O-free on the hot path. SignatureValidator has no async overload in this
-                    // library version — only a cold-start / key-rotation miss ever awaits real I/O here.
+                    // Blocking is safe: SignatureValidator has no async overload and the JWKS is cached in memory.
                     var jwk = jwks.GetKeyAsync(kid, CancellationToken.None).GetAwaiter().GetResult()
                         ?? throw new SecurityTokenInvalidSignatureException($"No JWKS key found for kid '{kid}'.");
 
@@ -585,10 +595,7 @@ public static class NeonAuthServiceExtensions
                     if (!verifier.VerifySignature(signature))
                         throw new SecurityTokenInvalidSignatureException("Ed25519 signature verification failed.");
 
-                    // MUST return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken — ASP.NET Core 8+
-                    // uses JsonWebTokenHandler internally. Returning a
-                    // System.IdentityModel.Tokens.Jwt.JwtSecurityToken here fails with IDX10506
-                    // ("SignatureValidator returned a token of an unexpected type").
+                    // Must be JsonWebToken: ASP.NET Core 8+ rejects a JwtSecurityToken here with IDX10506.
                     return jwt;
                 };
             });
@@ -600,6 +607,12 @@ public static class NeonAuthServiceExtensions
 }
 ```
 
+Two details of the validator above: it returns `Microsoft.IdentityModel.JsonWebTokens.JsonWebToken`
+because ASP.NET Core 8+ uses `JsonWebTokenHandler` internally — returning a
+`System.IdentityModel.Tokens.Jwt.JwtSecurityToken` fails with IDX10506 ("SignatureValidator returned a
+token of an unexpected type"); and the blocking `GetResult()` is I/O-free on the hot path, since only a
+cold-start or key-rotation miss ever awaits real I/O.
+
 ### Protected Endpoints
 
 ```csharp

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