@instavar/mcp-server 0.4.1 → 0.5.0

package/dist/index.js

@@ -4,10 +4,103 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// src/public-templates.ts
+// src/creative-guides.ts
 import { z } from "zod";
+
+// src/creative-guides.generated.ts
+var CREATIVE_GUIDES = [
+  {
+    "id": "visual-copy",
+    "title": "Concise plain and poetic visual copy",
+    "uri": "instavar://creative-guides/visual-copy",
+    "text": "# Write concise text for visual stories\n\nStatus: practical guidance, adapted from documented writing methods and bounded human feedback. This is not a measured guarantee of comprehension or engagement.\n\nUse for carousel headlines, supporting text, captions and video scripts. Begin with plain language. Add poetic expression when the brief asks for an experience or mood; keep instructions, factual claims and interface states literal.\n\n## Start with the viewer and the evidence\n\nName the audience, what they already know, the one idea they should understand, and the action or feeling the piece invites. List supplied facts and necessary qualifications separately from imagined details. Inspect the accompanying image before describing it. If it is unavailable, ask for context or mark the visual description as a proposal.\n\nDecide what the image demonstrates and what the words must add. A caption can rely on an accompanying picture only when the intended viewer receives that picture. Provide a self-contained alternative description for accessibility and text-only reuse.\n\n## Expand, select, connect, compress\n\n1. Expand enough to understand the full thought. Find the concrete objects, actions, relationships, evidence and limits.\n2. Select what must survive. In an explanation, preserve the causal link, units, conditions and uncertainty. In poetic copy, preserve the scene, voice and details that carry the experience.\n3. Connect the ideas in the order a new viewer needs them. Each slide or scene should advance the explanation or experience.\n4. Compress by removing repeated meaning, vague labels and redundant explanations. Read it again against the source. Shorter wording must not make the claim stronger.\n\nTreat brevity as revision pressure, not a word-count target. If a condition matters to the decision, retain it close to that decision. A tiny footnote or a later slide may be missed when the current slide is shared alone.\n\n## Use poetic language selectively\n\nLet a concrete action or sensory detail suggest emotion before naming the emotion. Choose details that belong to this scene. Movement, posture, pressure, temperature, hesitation and small corrections can matter as much as sight or sound. Do not force every sense into a passage.\n\nMetaphor, personification and rhythm should serve one governing idea. Remove mixed metaphors and phrases that could describe any product. Leave room for interpretation in expressive copy, but do not leave factual instructions ambiguous. Do not invent an observed event, testimonial, feeling or product result. Sensuality is an optional requested mode, not a default meaning of poetic.\n\n## Draft examples\n\nThese are newly authored teaching examples, not approved campaign copy.\n\n| Purpose             | Weak draft                                    | More concrete draft                                                   | What must remain                                        |\n| ------------------- | --------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------- |\n| Product instruction | Experience seamless creative transformation.  | Choose a clip. Add your caption. Preview the result.                  | Name only actions the product actually supports.        |\n| Quiet atmosphere    | Discover the magic of a new morning.          | The kettle clicks. Light reaches the table.                           | Use only supplied or explicitly imagined scene details. |\n| Evidence summary    | This format makes everyone understand faster. | In this review, two readers found the revised chart easier to follow. | Counts, population and evidence source must be real.    |\n\n## Deliver copy the creator can use\n\nReturn the title and caption separately. For a carousel or video, give one row per slide or scene: purpose, on-screen text, visual evidence, optional narration, and necessary qualification. Keep narration separate from on-screen copy so the screen need not repeat every spoken sentence.\n\nUse line breaks to shape meaningful groups. A single newline can keep short actions together; a blank line can mark a change of scene or thought. Follow the requested channel formatting. Neither spacing rule is universal.\n\nReview the actual render at the intended viewing size. Read the headline sequence alone, then the complete piece. Ask an unfamiliar viewer what happened, why, and what they would do next. A correct schema or short sentence does not establish reader understanding.\n\n## Reusable request\n\n\u201CUsing the supplied facts and visuals, draft concise copy for [audience] in [carousel/video format]. The viewer should understand [idea]. Use [plain/poetic] language. Give each scene a clear job, keep necessary conditions and evidence, and separate on-screen text from narration. Mark missing facts rather than inventing them. Return title, scene copy, caption and a short source-preservation check.\u201D\n\nSee the companion carousel, design and human-review guides. Source provenance and scope are recorded in the repository's September 2026 creative-playbook transfer report.\n"
+  },
+  {
+    "id": "carousel-stories",
+    "title": "Carousel story structures and transfer limits",
+    "uri": "instavar://creative-guides/carousel-stories",
+    "text": "# Choose a carousel story structure\n\nStatus: planning recipes adapted from the Eclat carousel programme. Recipes are not newly ported renderers or proof of audience performance.\n\nChoose a structure for the relationship being explained. A topic is not a template: circular motion, collisions and half-life can share a questioning structure while needing different diagrams, conditions and notation.\n\n## Existing Instavar templates\n\nThe HTTP template MCP currently scaffolds `listicle`, `manifesto`, `before-after` and `value-first-reveal`. Use `list_carousel_templates` and `get_carousel_schema` for the executable contract. The npm connector's video tools are a separate catalogue; these recipes do not imply npm carousel rendering support.\n\n- Listicle: parallel points that belong together.\n- Manifesto: one idea per slide in a connected progression.\n- Before/after: a genuine two-state contrast. This builder uses the first and last point; do not put essential intermediate reasoning into points that will be omitted.\n- Value-first reveal: useful information followed by evidence and a restrained product reveal. Do not invent product proof to fill a slot.\n\n## Newer educational recipes\n\n| Recipe                                 | Reading path                                                                                                                    | Use when                                                        | Preserve                                                         |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |\n| Question, evidence, explanation, check | Ask a specific question; show the relevant objects; explain the relationship; compare a case; ask a final check with its answer | A plausible misconception can be resolved visually              | The conditions that make the explanation true; a complete answer |\n| Observation to conclusion              | Show an observation; separate it from inference; compare explanations; state what can be concluded                              | The viewer must reason from visible evidence                    | Uncertainty and alternative explanations                         |\n| Worked comparison                      | Establish objects and quantities; show the symbolic relationship; substitute values; compare outcomes; conclude                 | A calculation needs to stay connected to the physical situation | Units, signs, definitions and unchanged variables                |\n| Action and correction                  | Show the setup; show an action; show a small correction; show the result                                                        | A practical action or sensory moment carries the story          | Safe technique, sequence and a truthful visible result           |\n\nThese can be drafted with one idea per slide using the manifesto skeleton, then reviewed and edited. Diagrams, equation blocks, editable placeholders and scientific apparatus require an appropriate construction layer; the text scaffold does not create or verify them. Never flatten a necessary diagram into decorative background artwork.\n\n## Lessons from the newer drafts\n\nKeep the relevant objects beside their equations so the viewer can connect symbols to the situation. State a useful symbolic relationship before numerical substitution when that helps the intended reader. Typeset fractions and symbols rather than using ambiguous slash text.\n\nGroup related words with their diagram. Give each calculation slide one main job. Remove duplicate results when the chart already carries them, but retain necessary assumptions. Make supporting text readable at delivery size. Recheck the whole deck after a local change.\n\nThe September 2026 Eclat batch included photoelectric threshold, circular motion, terminal velocity, sticking collision, wave amplitude, SHM turning points, standing waves, single-slit diffraction, field versus potential and half-life. A later six-deck revision applied earlier feedback to circular motion, SHM, standing waves, diffraction, field/potential and half-life. Those revised drafts were awaiting human review in the inspected record. This topic inventory is provenance, not a claim of ten new Instavar templates.\n\n## Delivery check\n\nReview full masters and every intended crop. A centred 4:5 crop of a 9:16 master was an Eclat production choice, not a universal platform requirement. Keep essential text, diagrams and qualifications inside the actual delivery region; verify current platform constraints separately before publication.\n\nTransfer the story method. Choose branding, type, texture, colour and imagery for the current creator. Eclat logos, source images, specialist answers and approval labels do not transfer automatically.\n"
+  },
+  {
+    "id": "visual-design",
+    "title": "UI, graphic design and video principles",
+    "uri": "instavar://creative-guides/visual-design",
+    "text": "# Make meaning visible across slides, video and interfaces\n\nStatus: practical design and review guidance. Context-specific aesthetic and outcome claims still need audience evidence.\n\n## Give attention a useful path\n\nStart with the audience's task. Identify what should be noticed first, what it means, where attention moves next, and what evidence supports the conclusion. Use hierarchy to express that path. The first meaningful text should usually carry the main idea; a small label above it earns its place only when it changes interpretation.\n\nMatch form to relationship: sequence for steps, side-by-side comparison for alternatives, a diagram for a mechanism, and an explicit state change for an action. Do not force every relationship into the same card layout. Make the heading sequence tell a connected story while the full reading supplies proof and limits.\n\n## Graphic design\n\nUse proximity, alignment, spacing, scale, weight and contrast to show grouping and priority. Keep type and colour roles consistent. Test text against its actual background and at its final size; do not assume a colour token alone guarantees contrast. Keep non-colour cues for important distinctions.\n\nTypography and colour can suggest tone, but their meanings depend on audience and context. A serif does not prove quality and a particular hue does not guarantee trust. Choose an expressive treatment only when the core content remains legible.\n\nReview local details, the whole image and the collection separately. A sharper object or stronger accent may weaken overall harmony. Compare against the verified source image; a file labelled original can still be an edited derivative. Retaining the original is a valid outcome.\n\n## Video and motion\n\nPlan what changes in the viewer's understanding across time. Show the setup before an action that requires it. Keep spatial and causal continuity when the viewer must follow a procedure. Use cuts, movement and sound to reveal a relationship or shift attention, not simply to add activity.\n\nGive viewers enough time to read the actual text and inspect the evidence. Test at normal playback speed. Treat muted review, picture review, narration review and the combined sound mix as separate checks. Time visible contact and its sound together when synchrony matters. Keep necessary information available when audio is absent.\n\nDo not import film pacing into interactive controls blindly. A film controls its timeline; an interface must preserve user agency, orientation and recovery.\n\n## UI and editing workflows\n\nMake the current object, possible action, saved state and consequence clear. Keep frequent controls visible at the intended viewport. Distinguish selection, dragging and text editing. Provide undo and understandable conflict handling for editable work. A preview and its export should reflect the same saved document.\n\nThese are review questions, not claims that the Eclat prototype's editor has been integrated into Instavar. Prototype gestures, exact button layouts and crop choices require fresh implementation and testing in the receiving product.\n\n## Verify the artifact\n\nInspect final-size text, crops, diagram labels, symbols, contrast, grouping and the overall sequence. For interfaces, also exercise keyboard use, focus, narrow viewports, saving, errors and recovery. For video, review timing and sound in playback rather than relying only on contact sheets.\n\nAutomated checks establish their measured properties, such as dimensions, parsing or bounds. They do not establish human preference, comprehension or campaign performance. Ask a new viewer to explain the idea or perform the intended task before making those stronger claims.\n"
+  },
+  {
+    "id": "human-review",
+    "title": "Human-guided copy, visual and media review",
+    "uri": "instavar://creative-guides/human-review",
+    "text": "# Preserve human feedback without inventing approval\n\nStatus: repository adaptation of the shared copy, UI/UX and media recording protocols. This guide is read-only; it does not store feedback or publish media.\n\nRecord a meaningful transition when a person reviews an identifiable draft, gives concrete feedback and a later revision responds. Preserve the exact draft and context, the feedback, the revision and the follow-up judgment. Do not treat every autonomous adjustment as human-guided work.\n\n## Keep one owning record\n\nUse an existing workstream report when available. Otherwise use `reports/copy/<workstream>/` for wording, `reports/ui-ux/` for layout and controls, or `reports/media/<workstream>/` for rendered picture, pacing, narration and sound. Link overlapping records instead of duplicating their histories. Keep old evidence at its existing paths.\n\nFor copy, preserve exact text, punctuation and line breaks. Record title and caption separately. For visual work, identify slide, route, state, viewport and before/after render. For media, also identify seconds or frames and playback conditions, including whether sound was on. If evidence is unavailable or a revision is source-only, say so.\n\n## Record template\n\n- Artifact and audience:\n- Before version, exact text or safe render reference:\n- Reviewed context, slide/range, viewport or playback conditions:\n- Human feedback, exact wording when safe:\n- Perceived problem and requested change:\n- Edit hypothesis:\n- Revision and after version:\n- Kept stable:\n- Follow-up judgment: not_judged / accepted_in_scope / rejected / mixed / superseded\n- Acceptance scope:\n- Publication: not_requested / requested / authorized / sent / verified, with evidence\n- Audience outcome: not_measured, or the actual observation and its limits\n- Source provenance, rights status and safe evidence references:\n- New issue and successor reference, if any:\n\nUse superseded only with a successor and keep the earlier judgment. A new complaint begins a new transition; chronology alone does not prove the previous change caused it.\n\n## What transfers\n\nKeep the problem-solving principle distinct from the particular remedy. \u201CThese calculation slides look cluttered\u201D can motivate grouping and removing repeated results. It does not justify removing assumptions from all science slides. A preference for one background, font size or line break applies to the reviewed context until further evidence supports transfer.\n\nApproval of a local detail is not approval of a whole image. Approval of a silent video does not approve the mix. Delivery is not approval, and approval is not evidence of audience impact. Silence remains not_judged.\n\nUse only public, owned or cleared examples in shared resources. Do not copy private screenshots, raw conversations, source photographs or unrelated account details to complete a record. A file hash identifies bytes; it does not establish rights, accuracy or quality. Recording feedback does not authorize publication or admission to a training or taste-critic corpus.\n"
+  }
+];
+
+// src/creative-guides.ts
+var creativeGuideIdSchema = z.enum([
+  "visual-copy",
+  "carousel-stories",
+  "visual-design",
+  "human-review"
+]);
+var CREATIVE_GUIDE_INDEX = CREATIVE_GUIDES.map(
+  ({ id: id2, title, uri }) => ({
+    id: id2,
+    title,
+    uri
+  })
+);
+function registerCreativeGuides(server) {
+  for (const guide of CREATIVE_GUIDES) {
+    server.registerResource(
+      guide.id,
+      guide.uri,
+      {
+        title: guide.title,
+        description: guide.title,
+        mimeType: "text/markdown"
+      },
+      async () => ({
+        contents: [
+          { uri: guide.uri, mimeType: "text/markdown", text: guide.text }
+        ]
+      })
+    );
+  }
+  server.registerTool(
+    "get_creative_guide",
+    {
+      title: "Get a visual communication guide",
+      description: "Read practical guidance before drafting concise plain or poetic copy, choosing carousel stories, designing visuals or recording human feedback. Returns guidance for the calling assistant to apply, not generated copy or saved feedback. Omit guideId to list guides.",
+      inputSchema: { guideId: creativeGuideIdSchema.optional() },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false
+      },
+      _meta: { securitySchemes: [{ type: "noauth" }] }
+    },
+    async ({ guideId }) => {
+      const guide = CREATIVE_GUIDES.find((entry) => entry.id === guideId);
+      return {
+        structuredContent: guide ? { guide } : { guides: CREATIVE_GUIDE_INDEX },
+        content: [
+          {
+            type: "text",
+            text: guide ? guide.text : CREATIVE_GUIDE_INDEX.map(
+              (entry) => `${entry.id}: ${entry.title} (${entry.uri})`
+            ).join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/public-templates.ts
+import { z as z2 } from "zod";
 var TEMPLATE_REPOSITORY = "https://github.com/instavar/remotion-templates";
 var TEMPLATE_ENDPOINT = "https://instavar.com/api/mcp/templates";
+var VOICE_STUDIO_URL = "https://instavar.com/voice";
 var templateIds = [
   "qa-ad",
   "proof-walkthrough",
@@ -15,8 +108,8 @@ var templateIds = [
   "social-remix",
   "finance-brief"
 ];
-var templateIdSchema = z.enum(templateIds);
-var aspectSchema = z.enum(["9:16", "4:5", "1:1"]);
+var templateIdSchema = z2.enum(templateIds);
+var aspectSchema = z2.enum(["9:16", "4:5", "1:1"]);
 var templates = [
   {
     id: "qa-ad",
@@ -86,6 +179,42 @@ var videoSpecSchema = {
         fixedDurationSec: { type: "number", exclusiveMinimum: 0 }
       }
     },
+    audio: {
+      type: "object",
+      properties: {
+        mode: { enum: ["auto", "narration", "music", "silent"] },
+        narrationText: { type: "string" },
+        narrationSrc: { type: "string" },
+        narrationVolume: { type: "number", minimum: 0, maximum: 1 },
+        musicSrc: { type: "string" },
+        musicVolume: { type: "number", minimum: 0, maximum: 1 },
+        ducking: { type: "boolean" },
+        narrationTiming: {
+          type: "object",
+          required: ["schemaVersion", "source", "durationMs", "segments"],
+          properties: {
+            schemaVersion: { const: "1.0" },
+            source: { const: "segmented-synthesis" },
+            durationMs: { type: "integer", minimum: 1 },
+            segments: {
+              type: "array",
+              minItems: 1,
+              maxItems: 24,
+              items: {
+                type: "object",
+                required: ["sceneId", "startMs", "endMs", "durationMs"],
+                properties: {
+                  sceneId: { type: "string", minLength: 1 },
+                  startMs: { type: "integer", minimum: 0 },
+                  endMs: { type: "integer", minimum: 1 },
+                  durationMs: { type: "integer", minimum: 1 }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     scenes: {
       type: "array",
       minItems: 1,
@@ -97,6 +226,8 @@ var videoSpecSchema = {
           kind: {
             enum: [
               "hero",
+              "statement",
+              "mechanism",
               "points",
               "equation",
               "video-window",
@@ -108,6 +239,17 @@ var videoSpecSchema = {
           timing: { type: "object" }
         }
       }
+    },
+    style: {
+      type: "object",
+      properties: {
+        theme: {
+          enum: ["default", "editorial-light", "editorial-dark", "clinical"]
+        },
+        variant: { type: "string" },
+        safeAreaProfile: { enum: ["baseline", "metaSafe"] },
+        showSceneLabels: { type: "boolean", default: false }
+      }
     }
   }
 };
@@ -134,35 +276,77 @@ function scaffoldVideoSpec(args) {
       content: {
         title: args.title,
         subtitle: "Replace with a concise promise"
-      }
+      },
+      timing: { durationMs: 4e3 }
     }
   ];
   if (args.templateId === "qa-ad" || args.templateId === "social-remix") {
     scenes.push({
       id: "source-video",
       kind: "video-window",
-      content: { src: args.mediaSrc ?? "public/replace-with-your-video.mp4" }
+      content: {
+        title: "See it in context",
+        src: args.mediaSrc ?? "public/replace-with-your-video.mp4"
+      },
+      timing: { durationMs: 7e3 }
+    });
+  }
+  if (args.templateId === "announcement-brief") {
+    scenes.push(
+      {
+        id: "context",
+        kind: "statement",
+        content: {
+          title: "Name the change",
+          subtitle: "Explain why it matters in one sentence"
+        },
+        timing: { durationMs: 6e3 }
+      },
+      {
+        id: "mechanism",
+        kind: "mechanism",
+        content: {
+          title: "Show how the change happens",
+          before: "Before",
+          after: "After"
+        },
+        timing: { durationMs: 7e3 }
+      },
+      {
+        id: "outcomes",
+        kind: "points",
+        content: {
+          title: "What changes",
+          points: ["First outcome", "Second outcome", "Third outcome"]
+        },
+        timing: { durationMs: 7e3 }
+      }
+    );
+  } else {
+    scenes.push({
+      id: args.templateId === "proof-walkthrough" ? "working" : "key-points",
+      kind: args.templateId === "proof-walkthrough" ? "equation" : "points",
+      content: args.templateId === "proof-walkthrough" ? {
+        title: "Work through the idea",
+        latexBlocks: ["x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}"]
+      } : {
+        title: "Key points",
+        points: [
+          "Replace with evidence",
+          "Replace with explanation",
+          "Replace with takeaway"
+        ]
+      },
+      timing: { durationMs: 8e3 }
     });
   }
-  scenes.push({
-    id: args.templateId === "proof-walkthrough" ? "working" : "key-points",
-    kind: args.templateId === "proof-walkthrough" ? "equation" : "points",
-    content: args.templateId === "proof-walkthrough" ? {
-      title: "Work through the idea",
-      latexBlocks: ["x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}"]
-    } : {
-      title: "Key points",
-      points: [
-        "Replace with evidence",
-        "Replace with explanation",
-        "Replace with takeaway"
-      ]
-    }
-  });
   scenes.push({
     id: "cta",
     kind: "cta",
-    content: { line1: "Replace with the next action" }
+    content: { line1: "Replace with the next action" },
+    timing: {
+      durationMs: args.templateId === "announcement-brief" ? 6e3 : 5e3
+    }
   });
   return {
     schemaVersion: "1.0",
@@ -171,16 +355,24 @@ function scaffoldVideoSpec(args) {
     meta: { title: args.title, tags: [] },
     target: { aspect: args.aspect, fps: 30, durationMode: "auto" },
     style: {
-      theme: "default",
+      theme: args.templateId === "announcement-brief" ? "editorial-light" : "default",
       variant: "default",
-      safeAreaProfile: "metaSafe"
+      safeAreaProfile: "metaSafe",
+      showSceneLabels: false
+    },
+    audio: {
+      mode: "silent",
+      narrationText: "",
+      narrationVolume: 1,
+      musicVolume: 0.16,
+      ducking: true
     },
-    audio: { ducking: true },
     assets: {},
     scenes
   };
 }
 function registerPublicTemplateTools(server) {
+  registerCreativeGuides(server);
   server.registerTool(
     "get_capabilities",
     {
@@ -195,13 +387,23 @@ function registerPublicTemplateTools(server) {
         apiKeyConfigured: Boolean(process.env.INSTAVAR_API_KEY?.trim()),
         repository: TEMPLATE_REPOSITORY,
         endpoint: TEMPLATE_ENDPOINT,
+        creativeGuides: CREATIVE_GUIDE_INDEX,
         localFeatures: [
           "template discovery",
           "VideoSpec schema and examples",
           "deterministic scaffolding",
           "local render instructions",
-          "render error diagnosis"
+          "render error diagnosis",
+          "keyless on-device narration with scene timing",
+          "every-scene preview frames",
+          "post-render audible-audio verification"
         ],
+        narration: {
+          url: VOICE_STUDIO_URL,
+          cost: "free",
+          apiKeyRequired: false,
+          guidance: "Write one paragraph per scene. Download the WAV and timing manifest, then apply both before rendering."
+        },
         accountFeatures: [
           "managed rendering and storage",
           "workflow review and approval",
@@ -284,9 +486,9 @@ ${template?.description ?? ""}`
       description: "Return a deterministic VideoSpec skeleton without writing files.",
       inputSchema: {
         templateId: templateIdSchema,
-        title: z.string().min(1).max(160),
+        title: z2.string().min(1).max(160),
         aspect: aspectSchema.default("9:16"),
-        mediaSrc: z.string().min(1).max(500).optional()
+        mediaSrc: z2.string().min(1).max(500).optional()
       },
       annotations
     },
@@ -304,7 +506,7 @@ ${template?.description ?? ""}`
       title: "Get local render instructions",
       description: "Return clone, install, validate, preview, and render commands.",
       inputSchema: {
-        client: z.enum(["codex", "claude-code", "manual"]).default("manual")
+        client: z2.enum(["codex", "claude-code", "manual"]).default("manual")
       },
       annotations
     },
@@ -313,9 +515,12 @@ ${template?.description ?? ""}`
         `git clone ${TEMPLATE_REPOSITORY}.git`,
         "cd remotion-templates",
         "npm install",
+        `# Generate one narration paragraph per scene at ${VOICE_STUDIO_URL}`,
+        "npm run video:timing -- path/to/video.video.json --audio public/generated/narration.wav --manifest path/to/narration.timing.json",
         "npm run video:validate -- path/to/video.video.json",
         "npm run video:preview -- path/to/video.video.json",
-        "npm run video:render -- path/to/video.video.json"
+        "npm run video:render -- path/to/video.video.json",
+        "npm run video:qa -- path/to/video.video.json path/to/video.mp4"
       ];
       return result(
         { repository: TEMPLATE_REPOSITORY, client, commands },
@@ -328,7 +533,7 @@ ${template?.description ?? ""}`
     {
       title: "Diagnose render error",
       description: "Classify a local validation or render error.",
-      inputSchema: { errorText: z.string().min(1).max(1e4) },
+      inputSchema: { errorText: z2.string().min(1).max(1e4) },
       annotations
     },
     async ({ errorText }) => {
@@ -346,7 +551,7 @@ ${template?.description ?? ""}`
 }
 
 // src/tools.ts
-import { z as z3 } from "zod";
+import { z as z5 } from "zod";
 
 // src/http.ts
 import { randomUUID } from "crypto";
@@ -470,7 +675,7 @@ async function runTool(fn) {
 }
 
 // src/brief-schema.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var PUBLISH_TARGETS = [
   "linkedin",
   "x",
@@ -502,16 +707,16 @@ var REFERENCE_ROLES = [
   "environment",
   "style"
 ];
-var optionalDirectionText = z2.string().trim().min(1).max(500).optional();
-var visualDirectionSchema = z2.object({
+var optionalDirectionText = z3.string().trim().min(1).max(500).optional();
+var visualDirectionSchema = z3.object({
   communicationJob: optionalDirectionText,
   emotionalTarget: optionalDirectionText,
-  attentionPath: z2.object({
+  attentionPath: z3.object({
     first: optionalDirectionText,
     next: optionalDirectionText,
     proof: optionalDirectionText
   }).optional(),
-  visualLanguage: z2.object({
+  visualLanguage: z3.object({
     space: optionalDirectionText,
     line: optionalDirectionText,
     shape: optionalDirectionText,
@@ -520,24 +725,24 @@ var visualDirectionSchema = z2.object({
     movement: optionalDirectionText,
     rhythm: optionalDirectionText
   }).optional(),
-  camera: z2.object({
+  camera: z3.object({
     shotSize: optionalDirectionText,
     angle: optionalDirectionText,
     movement: optionalDirectionText,
     lens: optionalDirectionText
   }).optional()
 });
-var generationContractSchema = z2.object({
-  globalInvariants: z2.array(z2.string().trim().min(1).max(300)).max(20).optional(),
-  shotDelta: z2.string().trim().min(1).max(500).optional(),
-  referenceBindings: z2.array(
-    z2.object({
-      assetId: z2.string().trim().min(1).max(200),
-      roles: z2.array(z2.enum(REFERENCE_ROLES)).min(1).max(7)
+var generationContractSchema = z3.object({
+  globalInvariants: z3.array(z3.string().trim().min(1).max(300)).max(20).optional(),
+  shotDelta: z3.string().trim().min(1).max(500).optional(),
+  referenceBindings: z3.array(
+    z3.object({
+      assetId: z3.string().trim().min(1).max(200),
+      roles: z3.array(z3.enum(REFERENCE_ROLES)).min(1).max(7)
     })
   ).max(20).optional(),
-  prohibitedChanges: z2.array(z2.string().trim().min(1).max(300)).max(20).optional(),
-  reviewCriteria: z2.array(z2.string().trim().min(1).max(300)).max(20).optional()
+  prohibitedChanges: z3.array(z3.string().trim().min(1).max(300)).max(20).optional(),
+  reviewCriteria: z3.array(z3.string().trim().min(1).max(300)).max(20).optional()
 });
 var REGION_NAMES = [
   "background",
@@ -554,47 +759,92 @@ var ASSET_ROLES = [
   "lower-third",
   "diagram-node"
 ];
-var assetSlotStyleSchema = z2.object({
-  opacity: z2.number().min(0).max(1).optional(),
-  fit: z2.enum(["cover", "contain"]).optional(),
-  z: z2.number().optional()
+var assetSlotStyleSchema = z3.object({
+  opacity: z3.number().min(0).max(1).optional(),
+  fit: z3.enum(["cover", "contain"]).optional(),
+  z: z3.number().optional()
 }).strict();
-var assetSlotSchema = z2.object({
-  id: z2.string().min(1),
-  sceneId: z2.string().min(1).optional(),
-  region: z2.enum(REGION_NAMES),
-  role: z2.enum(ASSET_ROLES),
-  kind: z2.enum(["image", "video"]),
-  source: z2.enum(["auto", "stock", "generate"]),
-  intent: z2.string(),
+var assetSlotSchema = z3.object({
+  id: z3.string().min(1),
+  sceneId: z3.string().min(1).optional(),
+  region: z3.enum(REGION_NAMES),
+  role: z3.enum(ASSET_ROLES),
+  kind: z3.enum(["image", "video"]),
+  source: z3.enum(["auto", "stock", "generate"]),
+  intent: z3.string(),
   style: assetSlotStyleSchema.optional(),
-  timing: z2.object({
-    fromPct: z2.number().min(0).max(1).optional(),
-    toPct: z2.number().min(0).max(1).optional()
+  timing: z3.object({
+    fromPct: z3.number().min(0).max(1).optional(),
+    toPct: z3.number().min(0).max(1).optional()
   }).strict().optional(),
-  url: z2.string().url().optional()
+  url: z3.string().url().optional()
 }).strict();
-var briefStepSchema = z2.object({
-  label: z2.string(),
-  latex: z2.string().optional(),
-  explanation: z2.string().optional()
+var briefStepSchema = z3.object({
+  label: z3.string(),
+  latex: z3.string().optional(),
+  explanation: z3.string().optional()
+});
+var briefAudioLayerSchema = z3.object({
+  id: z3.string().min(1),
+  src: z3.string().url(),
+  startFrame: z3.number().int().nonnegative().default(0),
+  durationInFrames: z3.number().int().positive().optional(),
+  volume: z3.number().min(0).max(1).default(1),
+  fadeFrames: z3.number().int().nonnegative().default(0),
+  role: z3.enum(["music", "foley", "transition", "effect"])
 });
-var briefAudioLayerSchema = z2.object({
-  id: z2.string().min(1),
-  src: z2.string().url(),
-  startFrame: z2.number().int().nonnegative().default(0),
-  durationInFrames: z2.number().int().positive().optional(),
-  volume: z2.number().min(0).max(1).default(1),
-  fadeFrames: z2.number().int().nonnegative().default(0),
-  role: z2.enum(["music", "foley", "transition", "effect"])
+var protectedRegionEffectSchema = z3.object({
+  id: z3.string().min(1).max(80),
+  kind: z3.literal("border-glint"),
+  coordinateSpace: z3.literal("output-frame-v1").default("output-frame-v1"),
+  region: z3.object({
+    leftPercent: z3.number().min(0).max(100),
+    topPercent: z3.number().min(0).max(100),
+    widthPercent: z3.number().positive().max(100),
+    heightPercent: z3.number().positive().max(100)
+  }),
+  startFrame: z3.number().int().nonnegative().default(0),
+  endFrame: z3.number().int().positive(),
+  speedUpFrame: z3.number().int().nonnegative().optional(),
+  color: z3.string().max(64).default("#ffffff"),
+  thicknessPercent: z3.number().positive().max(20).default(3)
+}).superRefine((effect2, context) => {
+  if (effect2.region.leftPercent + effect2.region.widthPercent > 100) {
+    context.addIssue({
+      code: "custom",
+      message: "Protected region exceeds the output frame width.",
+      path: ["region", "widthPercent"]
+    });
+  }
+  if (effect2.region.topPercent + effect2.region.heightPercent > 100) {
+    context.addIssue({
+      code: "custom",
+      message: "Protected region exceeds the output frame height.",
+      path: ["region", "heightPercent"]
+    });
+  }
+  if (effect2.endFrame <= effect2.startFrame) {
+    context.addIssue({
+      code: "custom",
+      message: "Effect endFrame must be after startFrame.",
+      path: ["endFrame"]
+    });
+  }
+  if (effect2.speedUpFrame !== void 0 && (effect2.speedUpFrame < effect2.startFrame || effect2.speedUpFrame >= effect2.endFrame)) {
+    context.addIssue({
+      code: "custom",
+      message: "speedUpFrame must fall inside the effect window.",
+      path: ["speedUpFrame"]
+    });
+  }
 });
-var beatVisualRequestSchema = z2.object({
-  intent: z2.string().trim().min(1).optional(),
-  media: z2.enum(["still", "motion"]).default("still"),
-  source: z2.enum(["auto", "stock", "generate"]).default("auto")
+var beatVisualRequestSchema = z3.object({
+  intent: z3.string().trim().min(1).optional(),
+  media: z3.enum(["still", "motion"]).default("still"),
+  source: z3.enum(["auto", "stock", "generate"]).default("auto")
 }).strict();
-var briefSceneSchema = z2.object({
-  type: z2.enum([
+var briefSceneSchema = z3.object({
+  type: z3.enum([
     "hero",
     "points",
     "equation",
@@ -617,154 +867,428 @@ var briefSceneSchema = z2.object({
     "image-window",
     "custom"
   ]),
-  durationInFrames: z2.number().optional(),
-  narrationText: z2.string().optional(),
+  durationInFrames: z3.number().optional(),
+  narrationText: z3.string().optional(),
   visualResolution: beatVisualRequestSchema.optional(),
-  title: z2.string().optional(),
-  subtitle: z2.string().optional(),
-  text: z2.string().optional(),
-  points: z2.array(z2.string()).optional(),
-  latex: z2.string().optional(),
-  value: z2.union([z2.string(), z2.number()]).optional(),
-  max: z2.number().optional(),
-  label: z2.string().optional(),
-  unit: z2.string().optional(),
-  prefix: z2.string().optional(),
-  suffix: z2.string().optional(),
-  decimals: z2.number().optional(),
-  color: z2.string().optional(),
-  tone: z2.string().optional(),
-  iconKey: z2.string().optional(),
-  stepNumber: z2.number().optional(),
-  totalSteps: z2.number().optional(),
-  items: z2.array(z2.object({ label: z2.string(), value: z2.number() })).optional(),
-  src: z2.string().optional(),
-  caption: z2.string().optional(),
+  title: z3.string().optional(),
+  subtitle: z3.string().optional(),
+  text: z3.string().optional(),
+  points: z3.array(z3.string()).optional(),
+  latex: z3.string().optional(),
+  value: z3.union([z3.string(), z3.number()]).optional(),
+  max: z3.number().optional(),
+  label: z3.string().optional(),
+  unit: z3.string().optional(),
+  prefix: z3.string().optional(),
+  suffix: z3.string().optional(),
+  decimals: z3.number().optional(),
+  color: z3.string().optional(),
+  tone: z3.string().optional(),
+  iconKey: z3.string().optional(),
+  stepNumber: z3.number().optional(),
+  totalSteps: z3.number().optional(),
+  items: z3.array(z3.object({ label: z3.string(), value: z3.number() })).optional(),
+  src: z3.string().optional(),
+  caption: z3.string().optional(),
   // A-roll generation (video-window scenes): source "generate" triggers
   // flag-gated WaveSpeed image/video gen server-side from generatePrompt;
   // "url" (default) uses src as-is. Kept in sync with the app's
   // briefSceneSchema - see the parity test in the app suite.
-  source: z2.enum(["url", "generate"]).optional(),
-  generatePrompt: z2.string().optional(),
+  source: z3.enum(["url", "generate"]).optional(),
+  generatePrompt: z3.string().optional(),
   generationContract: generationContractSchema.optional(),
-  trimStartSeconds: z2.number().nonnegative().optional(),
-  trimEndSeconds: z2.number().positive().optional(),
-  playbackRate: z2.number().min(0.25).max(8).optional(),
-  objectFit: z2.enum(["cover", "contain"]).optional(),
-  objectPosition: z2.string().optional(),
-  scaleFrom: z2.number().min(0.5).max(2).optional(),
-  scaleTo: z2.number().min(0.5).max(2).optional(),
-  panFromX: z2.number().min(-50).max(50).optional(),
-  panToX: z2.number().min(-50).max(50).optional(),
-  panFromY: z2.number().min(-50).max(50).optional(),
-  panToY: z2.number().min(-50).max(50).optional(),
-  routeFrom: z2.string().optional(),
-  routeTo: z2.string().optional(),
-  routeLabel: z2.string().optional(),
-  overlayKind: z2.enum(["none", "hook", "stage", "end-card"]).optional(),
-  overlayPosition: z2.enum(["center", "top", "bottom"]).optional(),
-  accentColor: z2.string().optional(),
-  overlayBackgroundColor: z2.string().optional(),
-  cutFlash: z2.boolean().optional(),
-  muted: z2.boolean().optional()
+  trimStartSeconds: z3.number().nonnegative().optional(),
+  trimEndSeconds: z3.number().positive().optional(),
+  playbackRate: z3.number().min(0.25).max(8).optional(),
+  objectFit: z3.enum(["cover", "contain"]).optional(),
+  objectPosition: z3.string().optional(),
+  scaleFrom: z3.number().min(0.5).max(2).optional(),
+  scaleTo: z3.number().min(0.5).max(2).optional(),
+  panFromX: z3.number().min(-50).max(50).optional(),
+  panToX: z3.number().min(-50).max(50).optional(),
+  panFromY: z3.number().min(-50).max(50).optional(),
+  panToY: z3.number().min(-50).max(50).optional(),
+  routeFrom: z3.string().optional(),
+  routeTo: z3.string().optional(),
+  routeLabel: z3.string().optional(),
+  overlayKind: z3.enum(["none", "hook", "stage", "end-card"]).optional(),
+  overlayPosition: z3.enum(["center", "top", "bottom"]).optional(),
+  accentColor: z3.string().optional(),
+  overlayBackgroundColor: z3.string().optional(),
+  cutFlash: z3.boolean().optional(),
+  muted: z3.boolean().optional(),
+  protectedRegionEffects: z3.array(protectedRegionEffectSchema).max(4).optional(),
+  flashAtFrame: z3.number().int().nonnegative().optional(),
+  flashDurationFrames: z3.number().int().positive().max(15).optional()
 });
-var directionsBriefSchema = z2.object({
-  subtitle: z2.string().optional(),
-  unitLabel: z2.string().optional(),
-  distanceTimeChip: z2.string().optional(),
-  clips: z2.array(
-    z2.object({
-      src: z2.string(),
-      trimStartSeconds: z2.number().optional(),
-      trimEndSeconds: z2.number(),
-      speed: z2.number().optional(),
-      mirrorFlip: z2.boolean().optional()
+var directionsBriefSchema = z3.object({
+  subtitle: z3.string().optional(),
+  unitLabel: z3.string().optional(),
+  distanceTimeChip: z3.string().optional(),
+  clips: z3.array(
+    z3.object({
+      src: z3.string(),
+      trimStartSeconds: z3.number().optional(),
+      trimEndSeconds: z3.number(),
+      speed: z3.number().optional(),
+      mirrorFlip: z3.boolean().optional()
     })
   ).min(1),
-  cues: z2.array(
-    z2.object({
-      atSeconds: z2.number(),
-      text: z2.string(),
-      arrow: z2.enum(["left", "right", "forward"]).optional(),
-      step: z2.number().optional()
+  cues: z3.array(
+    z3.object({
+      atSeconds: z3.number(),
+      text: z3.string(),
+      arrow: z3.enum(["left", "right", "forward"]).optional(),
+      step: z3.number().optional()
     })
   ),
-  outro: z2.object({
-    heading: z2.string().optional(),
-    body: z2.array(z2.string()).optional(),
-    seconds: z2.number().optional()
+  outro: z3.object({
+    heading: z3.string().optional(),
+    body: z3.array(z3.string()).optional(),
+    seconds: z3.number().optional()
   }).optional(),
-  music: z2.object({
-    perSegment: z2.array(
-      z2.object({
-        src: z2.string(),
-        clipIndexStart: z2.number().optional(),
-        hotOffsetSeconds: z2.number().optional(),
-        volume: z2.number().optional()
+  music: z3.object({
+    perSegment: z3.array(
+      z3.object({
+        src: z3.string(),
+        clipIndexStart: z3.number().optional(),
+        hotOffsetSeconds: z3.number().optional(),
+        volume: z3.number().optional()
       })
     ).optional(),
-    crossfadeSeconds: z2.number().optional()
+    crossfadeSeconds: z3.number().optional()
   }).optional()
 });
 var createBriefShape = {
-  title: z2.string().min(1).max(120).describe("Short title (max 120 chars)"),
-  script: z2.string().min(1).describe("Full narration script (sent to TTS)"),
-  caption: z2.string().min(1).describe("Social caption with hooks, hashtags, CTA"),
-  publishTarget: z2.enum(PUBLISH_TARGETS).describe("Target social platform"),
-  objective: z2.enum(BRIEF_OBJECTIVES).describe("Content objective (drives composition routing)"),
-  lessonTitle: z2.string().optional().describe("Display title rendered inside the video"),
+  title: z3.string().min(1).max(120).describe("Short title (max 120 chars)"),
+  script: z3.string().min(1).describe("Full narration script (sent to TTS)"),
+  caption: z3.string().min(1).describe("Social caption with hooks, hashtags, CTA"),
+  publishTarget: z3.enum(PUBLISH_TARGETS).describe("Target social platform"),
+  publishTargets: z3.array(z3.enum(PUBLISH_TARGETS)).max(9).optional().describe("All allowed social destinations for this video"),
+  objective: z3.enum(BRIEF_OBJECTIVES).describe("Content objective (drives composition routing)"),
+  targetDurationSeconds: z3.number().int().min(5).max(600).optional().describe("Requested final video duration in seconds"),
+  narrationMode: z3.enum(["tts", "off"]).optional().describe("Disable synthesized narration for source-audio or silent work"),
+  lessonTitle: z3.string().optional().describe("Display title rendered inside the video"),
   visualDirection: visualDirectionSchema.optional().describe(
     "Whole-video communication, attention, visual-language, and camera direction."
   ),
-  steps: z2.array(briefStepSchema).optional().describe("Structured steps for educational content (LaTeX)"),
-  scenes: z2.array(briefSceneSchema).optional().describe("Scene graph for the UniversalVideo composition"),
+  steps: z3.array(briefStepSchema).optional().describe("Structured steps for educational content (LaTeX)"),
+  scenes: z3.array(briefSceneSchema).optional().describe("Scene graph for the UniversalVideo composition"),
   // No zod .default() here: a default would materialize into the parsed tool
   // arguments and relay to /api/v1/jobs as if the caller stated it, corrupting
   // the resolution provenance the API echoes back. Unset must stay absent;
   // the API re-applies 9:16 server-side.
-  aspectRatio: z2.enum(ASPECT_RATIOS).optional().describe("Aspect ratio (defaults to 9:16 when omitted)"),
-  compositionId: z2.string().optional().describe("Remotion composition ID override (advanced)"),
-  voiceId: z2.string().optional().describe(
+  aspectRatio: z3.enum(ASPECT_RATIOS).optional().describe("Aspect ratio (defaults to 9:16 when omitted)"),
+  compositionId: z3.string().optional().describe("Remotion composition ID override (advanced)"),
+  voiceId: z3.string().optional().describe(
     "TTS narrator voice ID. Unknown IDs are rejected before rendering; when omitted, the org's saved voice preference or the system default is used and reported in the response's resolution block."
   ),
   directions: directionsBriefSchema.optional().describe(
     "DirectionsWalkthrough 'find-us' payload: source clips (legs), decision-point cues on the realtime walk timeline, outro, and optional music. Set compositionId 'DirectionsWalkthrough' (or objective 'directions')."
   ),
-  assetSlots: z2.array(assetSlotSchema).optional().describe(
+  assetSlots: z3.array(assetSlotSchema).optional().describe(
     "Optional storyboard asset slots: region-placed image/video assets or placeholders attached to the whole video or a specific scene."
   ),
-  audioLayers: z2.array(briefAudioLayerSchema).optional().describe("Optional typed music, Foley, transition, and effect layers.")
+  audioLayers: z3.array(briefAudioLayerSchema).optional().describe("Optional typed music, Foley, transition, and effect layers.")
 };
 var editBriefShape = {
-  jobId: z2.string().uuid().describe("The job to edit"),
-  title: z2.string().optional().describe("Updated title"),
-  script: z2.string().optional().describe("Updated narration script"),
-  caption: z2.string().optional().describe("Updated social caption"),
-  lessonTitle: z2.string().optional().describe("Updated lesson title"),
+  jobId: z3.string().uuid().describe("The job to edit"),
+  title: z3.string().optional().describe("Updated title"),
+  script: z3.string().optional().describe("Updated narration script"),
+  caption: z3.string().optional().describe("Updated social caption"),
+  lessonTitle: z3.string().optional().describe("Updated lesson title"),
+  narrationMode: z3.enum(["tts", "off"]).optional().describe("Updated synthesized narration mode"),
   visualDirection: visualDirectionSchema.optional().describe("Updated whole-video visual direction"),
-  steps: z2.array(briefStepSchema).optional().describe("Updated steps (replaces the array)"),
-  scenes: z2.array(briefSceneSchema).optional().describe("Updated scenes (replaces the array)"),
-  aspectRatio: z2.enum(ASPECT_RATIOS).optional().describe("Updated aspect ratio"),
-  objective: z2.enum(BRIEF_OBJECTIVES).optional().describe(
+  steps: z3.array(briefStepSchema).optional().describe("Updated steps (replaces the array)"),
+  scenes: z3.array(briefSceneSchema).optional().describe("Updated scenes (replaces the array)"),
+  aspectRatio: z3.enum(ASPECT_RATIOS).optional().describe("Updated aspect ratio"),
+  objective: z3.enum(BRIEF_OBJECTIVES).optional().describe(
     "Updated content objective. Re-routes the composition and triggers a re-render."
   ),
-  publishTarget: z2.enum(PUBLISH_TARGETS).optional().describe(
+  publishTarget: z3.enum(PUBLISH_TARGETS).optional().describe(
     "Updated target social platform. Distribution metadata only - does not trigger a re-render."
   ),
-  voiceId: z2.string().optional().describe(
+  publishTargets: z3.array(z3.enum(PUBLISH_TARGETS)).max(9).optional().describe("Replacement allowed social destination list"),
+  targetDurationSeconds: z3.number().int().min(5).max(600).optional().describe("Updated final video duration in seconds"),
+  voiceId: z3.string().optional().describe(
     "Updated TTS narrator voice ID. Triggers a re-render with the new voice."
   ),
-  assetSlots: z2.array(assetSlotSchema).optional().describe(
+  assetSlots: z3.array(assetSlotSchema).optional().describe(
     "Replacement storyboard asset slots. Omit to preserve existing slots; pass [] to clear them."
   ),
-  audioLayers: z2.array(briefAudioLayerSchema).optional().describe(
+  audioLayers: z3.array(briefAudioLayerSchema).optional().describe(
     "Replacement typed audio layers. Omit to preserve existing layers; pass [] to clear them."
   )
 };
 
+// src/render-diagnostics.ts
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function rows(value) {
+  return Array.isArray(value) ? value.map(record).filter((row) => !!row) : [];
+}
+function string(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function number(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function currentVideoArtifact(status) {
+  return rows(status?.artifacts).find(
+    (artifact) => artifact.artifactType === "video" && artifact.isCurrent === true
+  ) ?? null;
+}
+function verificationMatches(verifications, pattern) {
+  return verifications.filter(
+    (verification) => pattern.test(
+      [
+        verification.phase,
+        verification.checkKey,
+        verification.verifier,
+        JSON.stringify(verification.detailsJson ?? null)
+      ].map((value) => String(value ?? "")).join(" ")
+    )
+  );
+}
+function buildRenderDiagnosticSnapshot(params) {
+  const failed = [params.jobStatus, params.videoState].find(
+    (result2) => !result2.ok
+  );
+  if (failed) return failed;
+  const status = record(params.jobStatus.body);
+  const stateResponse = record(params.videoState.body);
+  const state = record(stateResponse?.state);
+  const runs = rows(status?.runs);
+  const latestRunId = string(status?.latestRunId);
+  const latestRun = runs.find((run) => string(run.id) === latestRunId) ?? runs[0] ?? null;
+  const videoArtifact = currentVideoArtifact(status);
+  const artifactMetadata = record(videoArtifact?.metadataJson);
+  const verifications = rows(status?.verificationTimeline);
+  const blankChecks = verificationMatches(verifications, /blank|black frame/i);
+  const placeholderChecks = verificationMatches(
+    verifications,
+    /placeholder|source clip|source asset/i
+  );
+  const rightsChecks = verificationMatches(
+    verifications,
+    /rights|licen[cs]|clearance/i
+  );
+  const currentVideoArtifactId = string(videoArtifact?.id);
+  const stateVideoArtifactId = string(state?.currentVideoArtifactId);
+  const expectedDurationSeconds = number(state?.durationSeconds) ?? number(status?.durationSec);
+  const actualDurationSeconds = number(videoArtifact?.durationSeconds) ?? number(artifactMetadata?.durationSeconds) ?? number(artifactMetadata?.durationSec) ?? number(artifactMetadata?.duration);
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      job: {
+        id: string(status?.id),
+        title: string(status?.title),
+        status: string(status?.status),
+        latestRunId
+      },
+      latestRun: latestRun ? {
+        id: string(latestRun.id),
+        runType: string(latestRun.runType),
+        status: string(latestRun.status),
+        errorCode: string(latestRun.errorCode),
+        errorMessage: string(latestRun.errorMessage)
+      } : null,
+      artifactBinding: {
+        jobCurrentVideoArtifactId: currentVideoArtifactId,
+        videoStateCurrentArtifactId: stateVideoArtifactId,
+        matches: currentVideoArtifactId && stateVideoArtifactId ? currentVideoArtifactId === stateVideoArtifactId : null,
+        currentVideoUrl: string(status?.currentVideoUrl) ?? string(state?.currentVideoUrl)
+      },
+      duration: {
+        expectedSeconds: expectedDurationSeconds,
+        actualSeconds: actualDurationSeconds,
+        deltaSeconds: expectedDurationSeconds !== null && actualDurationSeconds !== null ? Math.round(
+          (actualDurationSeconds - expectedDurationSeconds) * 1e3
+        ) / 1e3 : null
+      },
+      retryRecommendations: Array.isArray(status?.retryRecommendations) ? status?.retryRecommendations : [],
+      evidence: {
+        rights: rightsChecks,
+        blankFrames: blankChecks,
+        placeholders: placeholderChecks,
+        videoState: state
+      },
+      evidenceLimits: {
+        visualContentInspection: blankChecks.length || placeholderChecks.length ? "verification_rows_available" : "not_evaluated",
+        note: "No blank or placeholder verdict is inferred when the current verification timeline contains no matching check. Inspect the video artifact visually before deciding on an edit."
+      }
+    }
+  };
+}
+
+// src/design-action-schema.ts
+import { z as z4 } from "zod";
+var id = z4.string().min(1).max(120);
+var point = z4.object({ x: z4.number().min(0).max(1), y: z4.number().min(0).max(1) }).strict();
+var polygonShape = z4.object({
+  kind: z4.literal("polygon"),
+  points: z4.array(point).min(3).max(512)
+}).strict();
+var rasterShape = z4.object({
+  kind: z4.literal("raster"),
+  source: z4.object({
+    assetId: id,
+    expectedSha256: z4.string().regex(/^[a-f0-9]{64}$/),
+    sourceRange: z4.object({
+      startFrame: z4.number().int().nonnegative(),
+      endFrame: z4.number().int().positive()
+    }).strict().optional()
+  }).strict(),
+  widthPx: z4.number().int().positive().max(8192),
+  heightPx: z4.number().int().positive().max(8192)
+}).strict();
+var shape = z4.discriminatedUnion("kind", [polygonShape, rasterShape]);
+var mask = z4.object({
+  id,
+  shape,
+  operation: z4.enum(["add", "subtract"]),
+  inverted: z4.boolean().default(false),
+  feather: z4.number().finite().nonnegative().max(0.25).default(0),
+  allowedSupportMargin: z4.number().finite().nonnegative().max(0.25).default(0),
+  reviewState: z4.enum(["draft", "approved", "rejected"]),
+  provenance: z4.object({
+    kind: z4.enum(["manual", "imported", "model-proposed"]),
+    sourceAssetId: id.optional(),
+    modelId: z4.string().min(1).max(160).optional()
+  }).strict()
+}).strict();
+var transform = z4.object({
+  x: z4.number().min(0).max(1),
+  y: z4.number().min(0).max(1),
+  width: z4.number().positive().max(1),
+  height: z4.number().positive().max(1),
+  rotationDegrees: z4.number().min(-360).max(360),
+  opacity: z4.number().min(0).max(1)
+}).strict();
+var colourParameters = {
+  exposure: z4.number().finite().min(-2).max(2).default(0),
+  contrast: z4.number().finite().min(0.5).max(2).default(1),
+  saturation: z4.number().finite().min(0).max(2).default(1),
+  temperature: z4.number().finite().min(-1).max(1).default(0),
+  tint: z4.number().finite().min(-1).max(1).default(0)
+};
+var effect = z4.object({
+  id,
+  kind: z4.literal("local-colour"),
+  version: z4.literal(1),
+  maskId: id,
+  ...colourParameters
+}).strict();
+var motionPath = z4.object({
+  id,
+  kind: z4.literal("cubic-bezier"),
+  startFrame: z4.number().int().nonnegative(),
+  endFrame: z4.number().int().positive(),
+  start: point,
+  control1: point,
+  control2: point,
+  end: point,
+  easing: z4.enum(["linear", "ease-in", "ease-out", "ease-in-out"]),
+  orientToPath: z4.boolean().default(false)
+}).strict();
+var region = z4.object({ id, shape, label: z4.string().min(1).max(160) }).strict();
+var base = { actionId: id, sceneId: id };
+var vendoredDesignActionSchema = z4.discriminatedUnion("kind", [
+  z4.object({
+    ...base,
+    kind: z4.literal("set-layer-transform"),
+    layerId: id,
+    transform
+  }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-local-colour-effect"),
+    effectId: id,
+    parameters: z4.object(colourParameters).strict()
+  }).strict(),
+  z4.object({ ...base, kind: z4.literal("create-mask"), mask }).strict(),
+  z4.object({ ...base, kind: z4.literal("set-mask"), maskId: id, mask }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-mask-review-state"),
+    maskId: id,
+    reviewState: z4.enum(["draft", "approved", "rejected"])
+  }).strict(),
+  z4.object({ ...base, kind: z4.literal("delete-mask"), maskId: id }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("attach-effect"),
+    effect,
+    layerIds: z4.array(id).min(1).max(50)
+  }).strict(),
+  z4.object({ ...base, kind: z4.literal("remove-effect"), effectId: id }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-layer-text"),
+    layerId: id,
+    text: z4.string().max(1e4)
+  }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-layer-visibility"),
+    layerId: id,
+    visible: z4.boolean()
+  }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-layer-locked"),
+    layerId: id,
+    locked: z4.boolean()
+  }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-layer-mask-ids"),
+    layerId: id,
+    maskIds: z4.array(id).max(16)
+  }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-layer-order"),
+    orderedLayerIds: z4.array(id).min(1).max(500)
+  }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("set-motion-path"),
+    path: motionPath,
+    layerIds: z4.array(id).max(50).default([])
+  }).strict(),
+  z4.object({ ...base, kind: z4.literal("remove-motion-path"), pathId: id }).strict(),
+  z4.object({ ...base, kind: z4.literal("set-protected-region"), region }).strict(),
+  z4.object({
+    ...base,
+    kind: z4.literal("remove-protected-region"),
+    regionId: id
+  }).strict()
+]);
+var inspectDesignDocumentToolSchema = z4.object({
+  projectId: z4.string().uuid(),
+  documentId: z4.string().uuid(),
+  includeVersions: z4.boolean().default(true)
+}).strict();
+var applyDesignActionsToolSchema = z4.object({
+  projectId: z4.string().uuid(),
+  documentId: z4.string().uuid(),
+  actionGroupId: z4.string().min(1).max(120),
+  expectedVersion: z4.number().int().positive(),
+  actions: z4.array(vendoredDesignActionSchema).min(1).max(50),
+  clientCreatedAt: z4.string().datetime()
+}).strict();
+
 // src/tools.ts
-var uuid = (desc) => z3.string().uuid().describe(desc);
-var READ_ONLY = { readOnlyHint: true, openWorldHint: false };
+var uuid = (desc) => z5.string().uuid().describe(desc);
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
 var SAFE_WRITE = {
   readOnlyHint: false,
   destructiveHint: false,
@@ -778,8 +1302,8 @@ function registerTools(server) {
       title: "List jobs",
       description: "List recent video jobs for the current organization (newest first). Start here to discover job IDs; for one job's full detail use get_job_status.",
       inputSchema: {
-        limit: z3.number().int().min(1).max(50).default(10).describe("Number of jobs to return (default 10, max 50)"),
-        status: z3.enum([
+        limit: z5.number().int().min(1).max(50).default(10).describe("Number of jobs to return (default 10, max 50)"),
+        status: z5.enum([
           "queued",
           "rendering",
           "draft_ready",
@@ -820,6 +1344,23 @@ function registerTools(server) {
       () => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}/video-state`)
     )
   );
+  server.registerTool(
+    "diagnose_render",
+    {
+      title: "Diagnose render",
+      description: "Build one read-only troubleshooting snapshot from the current job status and video state. Reports run failures, artifact binding, duration evidence, retry recommendations, rights checks, and whether blank-frame or placeholder verification evidence exists. It does not visually inspect the video.",
+      inputSchema: { jobId: uuid("The job ID to diagnose") },
+      annotations: READ_ONLY
+    },
+    async ({ jobId }) => runTool(async () => {
+      const encodedJobId = encodeURIComponent(jobId);
+      const [jobStatus, videoState] = await Promise.all([
+        apiGet(`/api/v1/jobs/${encodedJobId}`),
+        apiGet(`/api/v1/jobs/${encodedJobId}/video-state`)
+      ]);
+      return buildRenderDiagnosticSnapshot({ jobStatus, videoState });
+    })
+  );
   server.registerTool(
     "get_job_metrics",
     {
@@ -827,7 +1368,7 @@ function registerTools(server) {
       description: "Get the latest platform engagement metric snapshots for a published job (newest first). Read-only. Only meaningful after publish_job; for render progress use get_job_status.",
       inputSchema: {
         jobId: uuid("The job ID"),
-        limit: z3.number().int().min(1).max(20).default(10).describe("Max metric snapshots (default 10, max 20)")
+        limit: z5.number().int().min(1).max(20).default(10).describe("Max metric snapshots (default 10, max 20)")
       },
       annotations: READ_ONLY
     },
@@ -843,10 +1384,10 @@ function registerTools(server) {
       title: "Get cost summary",
       description: "Query production infrastructure costs (Lambda, RunPod, R2, WaveSpeed, PoYo), optionally with reconciliation drift. This is spend data, not engagement \u2014 for a published job's audience numbers use get_job_metrics.",
       inputSchema: {
-        since: z3.string().optional().describe("ISO date \u2014 only include events after this date"),
-        provider: z3.enum(["runpod", "lambda", "r2", "wavespeed", "poyo", "all"]).default("all").describe("Filter by provider"),
-        groupBy: z3.enum(["provider", "job", "day"]).default("provider").describe("How to aggregate the summary"),
-        includeReconciliation: z3.boolean().default(false).describe("Include account-wide reconciliation events")
+        since: z5.string().optional().describe("ISO date \u2014 only include events after this date"),
+        provider: z5.enum(["runpod", "lambda", "r2", "wavespeed", "poyo", "all"]).default("all").describe("Filter by provider"),
+        groupBy: z5.enum(["provider", "job", "day"]).default("provider").describe("How to aggregate the summary"),
+        includeReconciliation: z5.boolean().default(false).describe("Include account-wide reconciliation events")
       },
       annotations: READ_ONLY
     },
@@ -862,13 +1403,50 @@ function registerTools(server) {
     {
       title: "Inspect workflow",
       description: "Inspect the current Studio workflow and its version history for a job.",
-      inputSchema: z3.object({ jobId: uuid("The job ID") }).strict(),
+      inputSchema: z5.object({ jobId: uuid("The job ID") }).strict(),
       annotations: READ_ONLY
     },
     async ({ jobId }) => runTool(
       () => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}/workflow`)
     )
   );
+  server.registerTool(
+    "inspect_design_document",
+    {
+      title: "Inspect design document",
+      description: "Inspect one versioned design document and its recent immutable version history. This tool never changes the document.",
+      inputSchema: inspectDesignDocumentToolSchema,
+      annotations: READ_ONLY
+    },
+    async ({ projectId, documentId, includeVersions }) => {
+      const query = new URLSearchParams({
+        documentId,
+        includeVersions: includeVersions ? "1" : "0"
+      });
+      return runTool(
+        () => apiGet(
+          `/api/v1/projects/${encodeURIComponent(
+            projectId
+          )}/design?${query.toString()}`
+        )
+      );
+    }
+  );
+  server.registerTool(
+    "apply_design_actions",
+    {
+      title: "Apply design actions",
+      description: "Apply a reviewed group of closed, invertible design actions to an expected document version. Inspect first. A stale version returns a readable conflict and does not overwrite customer work.",
+      inputSchema: applyDesignActionsToolSchema,
+      annotations: SAFE_WRITE
+    },
+    async (input) => runTool(
+      () => apiPost(
+        `/api/v1/projects/${encodeURIComponent(input.projectId)}/design`,
+        input
+      )
+    )
+  );
   server.registerTool(
     "create_video_brief",
     {
@@ -905,10 +1483,10 @@ function registerTools(server) {
     {
       title: "Draft workflow",
       description: "Create a durable Documentary Journey or Transformation Montage workflow version. Inspect first and pass its current version, or 0 only when no workflow exists.",
-      inputSchema: z3.object({
+      inputSchema: z5.object({
         jobId: uuid("The job ID"),
-        expectedVersion: z3.number().int().nonnegative().describe("Use 0 when no workflow exists yet"),
-        document: z3.unknown().describe("The complete Studio workflow document")
+        expectedVersion: z5.number().int().nonnegative().describe("Use 0 when no workflow exists yet"),
+        document: z5.unknown().describe("The complete Studio workflow document")
       }).strict(),
       annotations: SAFE_WRITE
     },
@@ -919,10 +1497,10 @@ function registerTools(server) {
     {
       title: "Patch workflow",
       description: "Create a new workflow version by recursively merging a patch into the current version.",
-      inputSchema: z3.object({
+      inputSchema: z5.object({
         jobId: uuid("The job ID"),
-        expectedVersion: z3.number().int().positive(),
-        patch: z3.record(z3.string(), z3.unknown())
+        expectedVersion: z5.number().int().positive(),
+        patch: z5.record(z5.string(), z5.unknown())
       }).strict(),
       annotations: SAFE_WRITE
     },
@@ -933,9 +1511,9 @@ function registerTools(server) {
     {
       title: "Validate workflow",
       description: "Validate and compile the inspected workflow version without rendering or publishing it.",
-      inputSchema: z3.object({
+      inputSchema: z5.object({
         jobId: uuid("The job ID"),
-        expectedVersion: z3.number().int().positive()
+        expectedVersion: z5.number().int().positive()
       }).strict(),
       annotations: SAFE_WRITE
     },
@@ -946,7 +1524,7 @@ function registerTools(server) {
     {
       title: "Preview workflow",
       description: "Return the current workflow's compiled UniversalVideo brief for a safe pre-render preview.",
-      inputSchema: z3.object({ jobId: uuid("The job ID") }).strict(),
+      inputSchema: z5.object({ jobId: uuid("The job ID") }).strict(),
       annotations: READ_ONLY
     },
     async ({ jobId }) => runTool(
@@ -960,10 +1538,10 @@ function registerTools(server) {
     {
       title: "Compare workflow versions",
       description: "Compare two durable workflow versions field by field.",
-      inputSchema: z3.object({
+      inputSchema: z5.object({
         jobId: uuid("The job ID"),
-        fromVersion: z3.number().int().positive(),
-        toVersion: z3.number().int().positive()
+        fromVersion: z5.number().int().positive(),
+        toVersion: z5.number().int().positive()
       }).strict(),
       annotations: READ_ONLY
     },
@@ -987,9 +1565,9 @@ function registerTools(server) {
     {
       title: "Approve workflow",
       description: "Validate and approve the inspected workflow version. This does not approve or publish the video job.",
-      inputSchema: z3.object({
+      inputSchema: z5.object({
         jobId: uuid("The job ID"),
-        expectedVersion: z3.number().int().positive()
+        expectedVersion: z5.number().int().positive()
       }).strict(),
       annotations: {
         readOnlyHint: false,
@@ -1046,7 +1624,7 @@ function registerTools(server) {
       inputSchema: {
         jobId: uuid("The current job ID"),
         sourceRunId: uuid("The current run ID"),
-        trigger: z3.enum(["user_requested", "verifier_recommendation"])
+        trigger: z5.enum(["user_requested", "verifier_recommendation"])
       },
       annotations: SAFE_WRITE
     },
@@ -1082,15 +1660,15 @@ function registerTools(server) {
       description: "Publish an APPROVED job to its connected social destination via the gated publish API. All production gates run (paid plan, ownership, abuse, QA, disclosure, destination, rights, moderation). Requires a key with publish scope; the post goes live on the external platform and cannot be recalled by the API. For YouTube pass youtubePrivacyStatus:'private' for safe runs.",
       inputSchema: {
         jobId: uuid("The approved job to publish"),
-        youtubePrivacyStatus: z3.enum(["private", "unlisted", "public"]).optional().describe("YouTube only. Use 'private' for safe dogfood runs."),
-        tiktokPostMode: z3.enum(["direct_publish", "draft_upload"]).optional().describe("TikTok only. Use 'draft_upload' for safe dogfood runs."),
-        connectedAccountDestinationId: z3.string().uuid().optional().describe(
+        youtubePrivacyStatus: z5.enum(["private", "unlisted", "public"]).optional().describe("YouTube only. Use 'private' for safe dogfood runs."),
+        tiktokPostMode: z5.enum(["direct_publish", "draft_upload"]).optional().describe("TikTok only. Use 'draft_upload' for safe dogfood runs."),
+        connectedAccountDestinationId: z5.string().uuid().optional().describe(
           "Specific destination when the org has multiple accounts for the provider."
         ),
-        confirmSyntheticDisclosure: z3.boolean().optional().describe(
+        confirmSyntheticDisclosure: z5.boolean().optional().describe(
           "Set true when the job requires an AI synthetic-media disclosure."
         ),
-        confirmQaOverride: z3.boolean().optional().describe("Set true to override a non-passing QA gate.")
+        confirmQaOverride: z5.boolean().optional().describe("Set true to override a non-passing QA gate.")
       },
       annotations: {
         readOnlyHint: false,
@@ -1113,7 +1691,7 @@ function registerTools(server) {
       title: "Connect social account",
       description: "Start connecting a social account headlessly (no local browser needed). Returns an approve URL + a short confirm code: open the URL in a browser signed in to Instavar, check the code matches THIS terminal, and approve. Then poll connect_account_status with the returned pairingId until it reports 'connected'.",
       inputSchema: {
-        provider: z3.enum([
+        provider: z5.enum([
           "youtube",
           "x",
           "tiktok",
@@ -1162,7 +1740,7 @@ function registerConfiguredTools(server, apiKey = process.env.INSTAVAR_API_KEY)
 // package.json
 var package_default = {
   name: "@instavar/mcp-server",
-  version: "0.4.1",
+  version: "0.5.0",
   mcpName: "com.instavar/mcp-server",
   description: "Make local videos with Instavar Remotion templates for free, then add an API key for hosted Studio workflows.",
   type: "module",
@@ -1236,7 +1814,12 @@ async function main() {
     process.stdout.write(HELP);
     return;
   }
-  const server = new McpServer({ name: "instavar", version: VERSION });
+  const server = new McpServer(
+    { name: "instavar", version: VERSION },
+    {
+      instructions: "Before drafting concise carousel or video copy, call get_creative_guide for visual-copy. Use the carousel-stories, visual-design and human-review guides as relevant. Apply them to the user brief; the guides do not generate, render, save or publish media."
+    }
+  );
   registerConfiguredTools(server);
   await server.connect(new StdioServerTransport());
 }