animarobo 0.0.0-stage → 0.1.0

package/assets/animarobo_brand.py

@@ -0,0 +1,143 @@
+"""
+Animarobo brand preamble for Manim scenes. Imported before the agent's scene code.
+
+- Brand palette as Manim colours: PRIMARY, SECONDARY, ACCENT, BACKGROUND, TEXT (+ PALETTE dict,
+  EXTRA list of further brand colours).
+- Background, default text/maths colour and brand fonts (HEADING_FONT, BODY_FONT) applied.
+- MathTex / Tex work without LaTeX: when no `latex` binary is found (or ANIMAROBO_TEX=mathjax),
+  formulas are typeset by Animarobo's bundled MathJax instead.
+"""
+import atexit
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import threading
+from pathlib import Path
+
+from manim import *  # noqa: F401,F403
+from manim import config, ManimColor, Text, MarkupText, Paragraph, MathTex, Tex, VMobject
+import manim.mobject.text.tex_mobject as _tex_mobject
+
+_BRAND = json.loads(os.environ.get("ANIMAROBO_BRAND", "{}"))
+PALETTE = {k: ManimColor(v) for k, v in _BRAND.get("palette", {}).items() if isinstance(v, str)}
+EXTRA = [ManimColor(c) for c in _BRAND.get("palette", {}).get("extra", []) if isinstance(c, str)]
+PRIMARY = PALETTE.get("primary", ManimColor("#58C4DD"))
+SECONDARY = PALETTE.get("secondary", ManimColor("#83C167"))
+ACCENT = PALETTE.get("accent", ManimColor("#FFFF00"))
+BACKGROUND = PALETTE.get("background", ManimColor("#000000"))
+TEXT = PALETTE.get("text", ManimColor("#FFFFFF"))
+HEADING_FONT = _BRAND.get("headingFont") or ""
+BODY_FONT = _BRAND.get("bodyFont") or HEADING_FONT
+
+if not _BRAND.get("transparent"):
+    config.background_color = BACKGROUND
+
+try:
+    import manimpango
+
+    for _f in _BRAND.get("fontFiles", []):
+        try:
+            manimpango.register_font(_f)
+        except Exception:
+            pass
+except Exception:
+    pass
+
+for _cls in (Text, MarkupText, Paragraph):
+    _cls.set_default(color=TEXT, **({"font": BODY_FONT} if BODY_FONT else {}))
+for _cls in (MathTex, Tex):
+    _cls.set_default(color=TEXT)
+VMobject.set_default(color=TEXT)
+
+
+# --- MathTex / Tex without LaTeX -----------------------------------------------------------
+
+class _MathJax:
+    """A persistent `node tex2svg.mjs` worker (one JSON line in, one out)."""
+
+    def __init__(self):
+        self.proc = None
+        self.lock = threading.Lock()
+
+    def svg(self, tex: str) -> str:
+        with self.lock:
+            if self.proc is None:
+                self.proc = subprocess.Popen(
+                    [os.environ.get("ANIMAROBO_NODE", "node"), os.environ["ANIMAROBO_TEX2SVG"]],
+                    stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True, bufsize=1,
+                )
+                atexit.register(self.proc.kill)
+            self.proc.stdin.write(json.dumps({"tex": tex}) + "\n")
+            self.proc.stdin.flush()
+            out = json.loads(self.proc.stdout.readline())
+        if "error" in out:
+            raise ValueError(f"TeX error in {tex!r}: {out['error']}")
+        return out["svg"]
+
+
+_mathjax = _MathJax()
+
+
+_OPEN = re.compile(r"\\special\{dvisvgm:raw <g id='([^']+)'>\}")
+_CLOSE = re.compile(r"\\special\{dvisvgm:raw </g>\}")
+
+
+def _to_mathjax(expr: str, text_mode: bool) -> str:
+    """
+    One MathJax math expression from what Manim would send to LaTeX. MathTex part markers
+    (dvisvgm specials) become \\cssId{…}{…}, which MathJax renders as the same <g id=…> groups;
+    in text mode (Tex) plain text is wrapped in \\text{} and $…$ stays maths.
+    """
+    expr = _CLOSE.sub("\x03", _OPEN.sub(lambda m: "\x01" + m.group(1) + "\x02", expr))
+    out, buf, math, i = [], "", not text_mode, 0
+
+    def flush():
+        nonlocal buf
+        if buf:
+            out.append(buf if math else "\\text{" + buf + "}")
+        buf = ""
+
+    while i < len(expr):
+        c = expr[i]
+        if c == "\x01":
+            j = expr.index("\x02", i)
+            flush()
+            out.append("\\cssId{" + expr[i + 1 : j] + "}{")
+            i = j + 1
+            continue
+        if c == "\x03":
+            flush()
+            out.append("}")
+        elif text_mode and c == "\\" and expr[i + 1 : i + 2] == "$":
+            buf += "\\$"
+            i += 1
+        elif text_mode and c == "$":
+            flush()
+            math = not math
+        else:
+            buf += c
+        i += 1
+    flush()
+    return "".join(out) or "\\text{}"
+
+
+def _mathjax_svg_file(expression, environment=None, tex_template=None):
+    text_mode = environment not in (None, "align*", "align", "equation*", "equation", "gather*", "displaymath")
+    expr = _to_mathjax(expression.strip(), text_mode)
+    if not text_mode and ("&" in expr or "\\\\" in expr):
+        expr = "\\begin{aligned}" + expr + "\\end{aligned}"
+    out_dir = Path(config.get_dir("tex_dir"))
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / f"mathjax-{hashlib.sha256(expr.encode()).hexdigest()[:16]}.svg"
+    if not out.exists():
+        out.write_text(_mathjax.svg(expr), encoding="utf-8")
+    return out
+
+
+TEX_ENGINE = "latex"
+if os.environ.get("ANIMAROBO_TEX") == "mathjax" or not shutil.which("latex"):
+    _tex_mobject.tex_to_svg_file = _mathjax_svg_file
+    TEX_ENGINE = "mathjax"

package/brand-kits/animarobo-demo/brand.json

@@ -0,0 +1,37 @@
+{
+  "id": "animarobo-demo",
+  "name": "Animarobo Demo",
+  "persona": {
+    "description": "Animarobo is a friendly, slightly mischievous robot animator who turns ideas into motion. Optimistic, precise, never cynical.",
+    "tone": ["playful", "confident", "clear"],
+    "audience": "Creators, marketers and developers who want studio-grade motion without a studio",
+    "doNot": ["use dark or violent imagery", "use more than two fonts", "use off-palette neon colors"]
+  },
+  "palette": {
+    "primary": "#5B5BF7",
+    "secondary": "#22D3EE",
+    "accent": "#FFB224",
+    "background": "#0E0F1A",
+    "text": "#F5F6FF",
+    "extra": ["#FF5D8F"]
+  },
+  "typography": {
+    "heading": { "family": "Space Grotesk", "googleFont": "Space Grotesk", "weights": [500, 700] },
+    "body": { "family": "Inter", "googleFont": "Inter", "weights": [400, 600, 700] }
+  },
+  "logo": {
+    "file": "logo.svg",
+    "fileOnDark": "logo-on-dark.svg",
+    "placement": "bottom-right",
+    "scale": 0.08
+  },
+  "visualStyle": {
+    "promptSuffix": "clean 3D-illustrated style, soft studio lighting, rounded friendly shapes, indigo and cyan color scheme with warm amber highlights, high detail",
+    "negativePrompt": "text, watermark, gore, horror, low quality, blurry, extra limbs, neon green",
+    "keywords": ["friendly robot", "rounded", "glossy", "optimistic"],
+    "referenceImages": [],
+    "cornerRadius": 28,
+    "motion": { "energy": "balanced", "defaultTransition": "fade", "transitionSeconds": 0.5 }
+  },
+  "voice": { "ttsVoice": "af_heart", "speed": 1.0 }
+}

package/brand-kits/animarobo-demo/logo-on-dark.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
+  <rect x="60" y="90" width="280" height="230" rx="70" fill="#5B5BF7"/>
+  <rect x="190" y="40" width="20" height="55" rx="10" fill="#5B5BF7"/>
+  <circle cx="200" cy="38" r="22" fill="#FFB224"/>
+  <rect x="100" y="140" width="200" height="110" rx="50" fill="#1B1C2E"/>
+  <circle cx="155" cy="195" r="24" fill="#22D3EE"/>
+  <circle cx="245" cy="195" r="24" fill="#22D3EE"/>
+  <path d="M170 280 Q200 300 230 280" stroke="#F5F6FF" stroke-width="12" fill="none" stroke-linecap="round"/>
+</svg>

package/brand-kits/animarobo-demo/logo.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
+  <rect x="60" y="90" width="280" height="230" rx="70" fill="#5B5BF7"/>
+  <rect x="190" y="40" width="20" height="55" rx="10" fill="#5B5BF7"/>
+  <circle cx="200" cy="38" r="22" fill="#FFB224"/>
+  <rect x="100" y="140" width="200" height="110" rx="50" fill="#0E0F1A"/>
+  <circle cx="155" cy="195" r="24" fill="#22D3EE"/>
+  <circle cx="245" cy="195" r="24" fill="#22D3EE"/>
+  <path d="M170 280 Q200 300 230 280" stroke="#F5F6FF" stroke-width="12" fill="none" stroke-linecap="round"/>
+</svg>

package/cli.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { createRequire as __cr } from 'node:module'; import { fileURLToPath as __fu } from 'node:url'; import { dirname as __dn } from 'node:path';
+const require = __cr(import.meta.url); const __filename = __fu(import.meta.url); const __dirname = __dn(__filename);
+import{C as h,d as y,x as w,y as f}from"./lib/UX7IAPLC.mjs";import{f as p,g}from"./lib/2YBE2P3S.mjs";import"./lib/2AVPIDPM.mjs";import{r as b}from"./lib/QWACG3XW.mjs";import{Q as m,V as l,W as c,Y as u,Z as d}from"./lib/YYR7MRVY.mjs";import"./lib/ZVOH525Q.mjs";import"./lib/US7HTISX.mjs";import"./lib/45MJLRTX.mjs";import"./lib/43MGJOQW.mjs";import"./lib/27YDEYYD.mjs";import"./lib/HWH5POFJ.mjs";import"./lib/ODDRYKUC.mjs";import{parseArgs as S}from"node:util";var v=()=>[{id:"s1",template:"logo-reveal",durationSeconds:3,props:{tagline:"Made to move",style:"scale"}},{id:"s2",template:"title-card",durationSeconds:3.5,props:{eyebrow:"Introducing",title:"Animarobo",subtitle:"Brand-true motion graphics, orchestrated by AI agents"}},{id:"s3",template:"kinetic-text",durationSeconds:3.5,props:{lines:["Open-source engines.","Generative models.","Your brand, every frame."],emphasis:["brand"]},transitionIn:{type:"slide",direction:"from-right",seconds:.5}},{id:"s4",template:"bullet-list",durationSeconds:4,props:{heading:"What it does",bullets:["Remotion motion templates","ComfyUI image & video models","Understands & extends footage"]},transitionIn:{type:"wipe",direction:"from-left",seconds:.5}},{id:"s5",template:"layers",durationSeconds:3,props:{background:{type:"grid",colors:["background","accent"]},layers:[{type:"shape",shape:"circle",x:.42,y:.25,w:.16,h:.284,fill:"accent",animationIn:"pop"},{type:"text",text:"Any layout. Any layer.",x:.1,y:.62,w:.8,h:.15,align:"center",fontSize:.08,startSeconds:.4,animationIn:"slide-up"}]},transitionIn:{type:"iris",direction:"from-right",seconds:.6}},{id:"s6",template:"quote",durationSeconds:3.5,props:{quote:"Like having a motion studio on call.",author:"Every content team, soon"}},{id:"s7",template:"end-card",durationSeconds:3.5,props:{headline:"Start creating",cta:"Connect your agent",url:"github.com/explorian006/animarobo"}}];var s=r=>console.log(typeof r=="string"?r:JSON.stringify(r,null,2)),j=r=>process.stderr.write(`\rrendering ${Math.round(r*100)}%   `);async function x(){let{positionals:r,values:e}=S({allowPositionals:!0,options:{http:{type:"boolean"},toolsets:{type:"string"},port:{type:"string",default:"3333"},host:{type:"string",default:"127.0.0.1"},aspect:{type:"string"},brand:{type:"string"},scale:{type:"string"},scene:{type:"string"},at:{type:"string"},project:{type:"string"},name:{type:"string"},text:{type:"string"},font:{type:"string"},weight:{type:"string"},out:{type:"string"},open:{type:"boolean"},ffmpeg:{type:"boolean"},voice:{type:"string"},"no-browser":{type:"boolean"},manim:{type:"boolean"},version:{type:"boolean",short:"v"},help:{type:"boolean",short:"h"}}}),[k,i]=r;if(e.version){let{readFileSync:o}=await import("node:fs"),{REPO_ROOT:t}=await import("./lib/UVU3FU34.mjs");return s(JSON.parse(o(`${t}/package.json`,"utf8")).version)}switch(k){case"mcp":{e.toolsets&&(process.env.ANIMAROBO_TOOLSETS=e.toolsets),(await import("./lib/5IWGRKCP.mjs")).resolveToolsets(process.env.ANIMAROBO_TOOLSETS);let{startHttp:o,startStdio:t}=await import("./lib/E2H6ESRH.mjs");e.http?await o(Number(e.port),e.host):await t();return}case"demo":{let o=await d({name:"demo",brandKitId:e.brand??"animarobo-demo",aspect:e.aspect??"16:9"}),t=await u(o.id,I=>{I.timeline.scenes=v()}),n=await p(t,{onProgress:j,scale:e.scale?Number(e.scale):1});process.stderr.write(`
+`),s({projectId:t.id,...n});break}case"render":{let o=await p(await c(a(i,"projectId")),{onProgress:j,scale:e.scale?Number(e.scale):1});process.stderr.write(`
+`),s(o);break}case"still":s(await g(await c(a(i,"projectId")),{sceneId:e.scene,seconds:e.at?Number(e.at):void 0,scale:e.scale?Number(e.scale):.5}));break;case"analyze":{let o=e.project??(await d({name:"analysis"})).id,t=await w(o,a(i,"video"));s({projectId:o,sourceAssetId:t.asset.id,lastFrameAssetId:t.lastFrameAsset.id,context:t.context});break}case"continue":s(await f({source:a(i,"video"),name:e.name??"continuation",brandKitId:e.brand}));break;case"check":s(y(await c(a(i,"projectId"))));break;case"wordmark":{let o=await h(a(i,"brandKitId"),{text:a(e.text,"--text"),family:e.font,weight:e.weight?Number(e.weight):void 0});return s(o)}case"deliver":{let{deliver:o}=await import("./lib/E5B5GBVG.mjs"),t=await o(r.slice(1),{name:e.name,dest:e.out?(await import("node:path")).resolve(e.out):void 0,open:e.open});return s({dir:t.dir,gallery:t.index,zip:t.zip,counts:t.counts})}case"setup":{let{setup:o}=await import("./lib/53WQ5F6R.mjs"),t=await o({ffmpeg:e.ffmpeg,browser:!e["no-browser"],voice:e.voice,manim:e.manim});s(t),process.exitCode=t.ok?0:1;return}case"doctor":{let{doctor:o}=await import("./lib/53WQ5F6R.mjs"),t=await o();for(let n of t.checks)process.stderr.write(`${n.status==="ok"?"\u2713":n.status==="warn"?"!":"\u2717"} ${n.name.padEnd(20)} ${n.detail}${n.fix?`
+    \u2192 ${n.fix}`:""}
+`);s({ok:t.ok,home:t.home}),process.exitCode=t.ok?0:1;return}case"projects":s(await l());break;case"brands":s((await m()).map(({kit:o,dir:t,builtin:n})=>({id:o.id,name:o.name,builtin:n,dir:t})));break;case"providers":s(b());break;default:s(["animarobo \u2013 brand-aware motion graphics & video engine (MCP server)","","  mcp [--http --port 3333] [--toolsets core,sound]   start MCP server (stdio by default)","  demo [--aspect 9:16]         render the demo timeline","  render <projectId>           render a project to MP4","  still <projectId> [--scene id | --at sec]","  analyze <video> [--project id]","  continue <video> --name <n>  start a project that extends a video","  check <projectId>            brand compliance report","  projects | brands | providers"].join(`
+`))}process.exit(0)}function a(r,e){if(!r)throw new Error(`Missing <${e}> argument`);return r}x().catch(r=>{console.error(r instanceof Error?r.message:r),process.exit(1)});

package/comfy-workflows/i2i-sdxl.json

@@ -0,0 +1,20 @@
+{
+  "_animarobo": {
+    "description": "Image-to-image (reference/brand-style conditioning) with an SDXL checkpoint. denoise controls how far it departs from the reference.",
+    "placeholders": ["prompt", "negative_prompt", "seed", "reference_image"]
+  },
+  "4": { "class_type": "CheckpointLoaderSimple", "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" } },
+  "10": { "class_type": "LoadImage", "inputs": { "image": "{{reference_image}}" } },
+  "11": { "class_type": "VAEEncode", "inputs": { "pixels": ["10", 0], "vae": ["4", 2] } },
+  "6": { "class_type": "CLIPTextEncode", "inputs": { "text": "{{prompt}}", "clip": ["4", 1] } },
+  "7": { "class_type": "CLIPTextEncode", "inputs": { "text": "{{negative_prompt}}", "clip": ["4", 1] } },
+  "3": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": "{{seed}}", "steps": 28, "cfg": 6, "sampler_name": "dpmpp_2m", "scheduler": "karras", "denoise": 0.6,
+      "model": ["4", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["11", 0]
+    }
+  },
+  "8": { "class_type": "VAEDecode", "inputs": { "samples": ["3", 0], "vae": ["4", 2] } },
+  "9": { "class_type": "SaveImage", "inputs": { "filename_prefix": "animarobo", "images": ["8", 0] } }
+}

package/comfy-workflows/i2v-wan22-5b.json

@@ -0,0 +1,156 @@
+{
+  "_animarobo": {
+    "description": "Wan 2.2 TI2V-5B image-to-video: animates {{init_image}} (a still, or the last frame of a previous clip for seamless continuation). Same model files as t2v-wan22-5b.",
+    "models": [
+      "diffusion_models/wan2.2_ti2v_5B_fp16.safetensors",
+      "text_encoders/umt5_xxl_fp8_e4m3fn_scaled.safetensors",
+      "vae/wan2.2_vae.safetensors"
+    ],
+    "placeholders": [
+      "prompt",
+      "negative_prompt",
+      "width",
+      "height",
+      "frames",
+      "fps",
+      "seed",
+      "init_image"
+    ]
+  },
+  "37": {
+    "class_type": "UNETLoader",
+    "inputs": {
+      "unet_name": "wan2.2_ti2v_5B_fp16.safetensors",
+      "weight_dtype": "default"
+    }
+  },
+  "38": {
+    "class_type": "CLIPLoader",
+    "inputs": {
+      "clip_name": "umt5_xxl_fp8_e4m3fn_scaled.safetensors",
+      "type": "wan",
+      "device": "default"
+    }
+  },
+  "39": {
+    "class_type": "VAELoader",
+    "inputs": {
+      "vae_name": "wan2.2_vae.safetensors"
+    }
+  },
+  "48": {
+    "class_type": "ModelSamplingSD3",
+    "inputs": {
+      "shift": 8,
+      "model": [
+        "37",
+        0
+      ]
+    }
+  },
+  "6": {
+    "class_type": "CLIPTextEncode",
+    "inputs": {
+      "text": "{{prompt}}",
+      "clip": [
+        "38",
+        0
+      ]
+    }
+  },
+  "7": {
+    "class_type": "CLIPTextEncode",
+    "inputs": {
+      "text": "{{negative_prompt}}",
+      "clip": [
+        "38",
+        0
+      ]
+    }
+  },
+  "55": {
+    "class_type": "Wan22ImageToVideoLatent",
+    "inputs": {
+      "width": "{{width}}",
+      "height": "{{height}}",
+      "length": "{{frames}}",
+      "batch_size": 1,
+      "vae": [
+        "39",
+        0
+      ],
+      "start_image": [
+        "56",
+        0
+      ]
+    }
+  },
+  "3": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": "{{seed}}",
+      "steps": 30,
+      "cfg": 5,
+      "sampler_name": "uni_pc",
+      "scheduler": "simple",
+      "denoise": 1,
+      "model": [
+        "48",
+        0
+      ],
+      "positive": [
+        "6",
+        0
+      ],
+      "negative": [
+        "7",
+        0
+      ],
+      "latent_image": [
+        "55",
+        0
+      ]
+    }
+  },
+  "8": {
+    "class_type": "VAEDecode",
+    "inputs": {
+      "samples": [
+        "3",
+        0
+      ],
+      "vae": [
+        "39",
+        0
+      ]
+    }
+  },
+  "57": {
+    "class_type": "CreateVideo",
+    "inputs": {
+      "images": [
+        "8",
+        0
+      ],
+      "fps": "{{fps}}"
+    }
+  },
+  "58": {
+    "class_type": "SaveVideo",
+    "inputs": {
+      "video": [
+        "57",
+        0
+      ],
+      "filename_prefix": "animarobo/video",
+      "format": "auto",
+      "codec": "auto"
+    }
+  },
+  "56": {
+    "class_type": "LoadImage",
+    "inputs": {
+      "image": "{{init_image}}"
+    }
+  }
+}

package/comfy-workflows/music-ace-step.json

@@ -0,0 +1,21 @@
+{
+  "_animarobo": {
+    "description": "ACE-Step v1 3.5B text-to-music (Apache-2.0). Mirrors ComfyUI's ACE-Step template; tags = style prompt, lyrics may be '[instrumental]'. Re-export from the official template if node names changed.",
+    "models": ["checkpoints/ace_step_v1_3.5b.safetensors"],
+    "placeholders": ["prompt", "duration", "seed"]
+  },
+  "40": { "class_type": "CheckpointLoaderSimple", "inputs": { "ckpt_name": "ace_step_v1_3.5b.safetensors" } },
+  "14": { "class_type": "TextEncodeAceStepAudio", "inputs": { "tags": "{{prompt}}", "lyrics": "[instrumental]", "lyrics_strength": 0.99, "clip": ["40", 1] } },
+  "44": { "class_type": "ConditioningZeroOut", "inputs": { "conditioning": ["14", 0] } },
+  "17": { "class_type": "EmptyAceStepLatentAudio", "inputs": { "seconds": "{{duration}}", "batch_size": 1 } },
+  "49": { "class_type": "ModelSamplingSD3", "inputs": { "shift": 5, "model": ["40", 0] } },
+  "52": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": "{{seed}}", "steps": 50, "cfg": 5, "sampler_name": "euler", "scheduler": "simple", "denoise": 1,
+      "model": ["49", 0], "positive": ["14", 0], "negative": ["44", 0], "latent_image": ["17", 0]
+    }
+  },
+  "18": { "class_type": "VAEDecodeAudio", "inputs": { "samples": ["52", 0], "vae": ["40", 2] } },
+  "59": { "class_type": "SaveAudioMP3", "inputs": { "audio": ["18", 0], "filename_prefix": "animarobo/music", "quality": "V0" } }
+}

package/comfy-workflows/t2i-sdxl.json

@@ -0,0 +1,19 @@
+{
+  "_animarobo": {
+    "description": "Text-to-image with any SDXL-class checkpoint using only core ComfyUI nodes. Swap ckpt_name for your model. For FLUX.2 klein / Z-Image / Qwen-Image, export their official ComfyUI template via Workflow → Export (API) and put the {{placeholders}} into the prompt/size/seed fields.",
+    "placeholders": ["prompt", "negative_prompt", "width", "height", "seed", "count"]
+  },
+  "4": { "class_type": "CheckpointLoaderSimple", "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" } },
+  "5": { "class_type": "EmptyLatentImage", "inputs": { "width": "{{width}}", "height": "{{height}}", "batch_size": "{{count}}" } },
+  "6": { "class_type": "CLIPTextEncode", "inputs": { "text": "{{prompt}}", "clip": ["4", 1] } },
+  "7": { "class_type": "CLIPTextEncode", "inputs": { "text": "{{negative_prompt}}", "clip": ["4", 1] } },
+  "3": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": "{{seed}}", "steps": 28, "cfg": 6.5, "sampler_name": "dpmpp_2m", "scheduler": "karras", "denoise": 1,
+      "model": ["4", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["5", 0]
+    }
+  },
+  "8": { "class_type": "VAEDecode", "inputs": { "samples": ["3", 0], "vae": ["4", 2] } },
+  "9": { "class_type": "SaveImage", "inputs": { "filename_prefix": "animarobo", "images": ["8", 0] } }
+}

package/comfy-workflows/t2v-wan22-5b.json

@@ -0,0 +1,24 @@
+{
+  "_animarobo": {
+    "description": "Wan 2.2 TI2V-5B text-to-video (Apache-2.0, runs on ~8-12GB VRAM with fp8/GGUF). Mirrors ComfyUI's official Wan2.2 5B template using native nodes. If your ComfyUI version names nodes differently, open the official template, Export (API), and re-insert the placeholders.",
+    "models": ["diffusion_models/wan2.2_ti2v_5B_fp16.safetensors", "text_encoders/umt5_xxl_fp8_e4m3fn_scaled.safetensors", "vae/wan2.2_vae.safetensors"],
+    "placeholders": ["prompt", "negative_prompt", "width", "height", "frames", "fps", "seed"]
+  },
+  "37": { "class_type": "UNETLoader", "inputs": { "unet_name": "wan2.2_ti2v_5B_fp16.safetensors", "weight_dtype": "default" } },
+  "38": { "class_type": "CLIPLoader", "inputs": { "clip_name": "umt5_xxl_fp8_e4m3fn_scaled.safetensors", "type": "wan", "device": "default" } },
+  "39": { "class_type": "VAELoader", "inputs": { "vae_name": "wan2.2_vae.safetensors" } },
+  "48": { "class_type": "ModelSamplingSD3", "inputs": { "shift": 8, "model": ["37", 0] } },
+  "6": { "class_type": "CLIPTextEncode", "inputs": { "text": "{{prompt}}", "clip": ["38", 0] } },
+  "7": { "class_type": "CLIPTextEncode", "inputs": { "text": "{{negative_prompt}}", "clip": ["38", 0] } },
+  "55": { "class_type": "Wan22ImageToVideoLatent", "inputs": { "width": "{{width}}", "height": "{{height}}", "length": "{{frames}}", "batch_size": 1, "vae": ["39", 0] } },
+  "3": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": "{{seed}}", "steps": 30, "cfg": 5, "sampler_name": "uni_pc", "scheduler": "simple", "denoise": 1,
+      "model": ["48", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["55", 0]
+    }
+  },
+  "8": { "class_type": "VAEDecode", "inputs": { "samples": ["3", 0], "vae": ["39", 0] } },
+  "57": { "class_type": "CreateVideo", "inputs": { "images": ["8", 0], "fps": "{{fps}}" } },
+  "58": { "class_type": "SaveVideo", "inputs": { "video": ["57", 0], "filename_prefix": "animarobo/video", "format": "auto", "codec": "auto" } }
+}

package/docs/CLIENTS.md

@@ -0,0 +1,164 @@
+# Using Animarobo from Claude, Codex, Cursor, VS Code, Windsurf and Gemini CLI
+
+Animarobo is one stdio MCP server, `npx -y animarobo mcp`, and the same
+build works in every client below. This page covers how to add it, what each client limits, and
+how to govern which tools an agent may call. The full tool reference, with read-only and
+destructive lists and ready-made approval snippets, is in [TOOLS.md](TOOLS.md).
+
+Client facts were checked in October 2026 against each client's docs or source code. Where a
+client doesn't document something, this page says so.
+
+## Before the first use
+
+```bash
+npx -y animarobo setup    # FFmpeg, render browser, fonts (~250 MB, once)
+npx -y animarobo doctor   # check the install
+```
+
+The first `npx` start downloads the package (about 30 s). Run `setup` once, or give the client a
+generous startup timeout: Codex's documented default is 10 s.
+
+## What the server does for every client
+
+| Concern | How Animarobo handles it |
+|---|---|
+| Tool names | Lowercase `[a-z0-9_]`, at most 22 characters, so prefixed names stay short: `mcp__animarobo__…` (Claude Code, Codex), `mcp_animarobo_…` (VS Code, Gemini CLI), server + tool ≤ 60 (Cursor). No hyphens or dots, which Codex rewrites. |
+| Schemas | Plain JSON Schema objects with no top-level unions, `$ref`, nullable unions, `$schema`, `propertyNames` or exclusive bounds. Each schema is under 1.4 kB, below Codex's 5 kB compaction threshold. The server validates the exact schema itself. |
+| Descriptions | Each is ≤ 1,024 characters with the purpose first. Server instructions are ≤ 4,096 characters (Claude Code's cut-off). |
+| Approvals | Every tool carries `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` and `title`, taken from one catalog (`src/mcp/toolCatalog.ts`). |
+| Timeouts | Anything that can take long accepts `async: true`. It returns a job id at once, and you poll `job_status`. Use it for renders in every client. |
+| No MCP roots (Codex; roots are deprecated in the 2026-07-28 spec) | `deliver` writes to `dest`, else the roots, else `ANIMAROBO_OUTPUT_DIR`, else the folder the client started the server in, else `~/.animarobo/deliveries`. |
+| No sampling (Codex, Gemini CLI, Cursor) | `produce_video` uses `ANTHROPIC_API_KEY` or `LLM_API_URL` if set. Otherwise the agent drives the same loop with the step tools: `storyboard_create` → `shot_produce` → `cut_assemble` → `editor_*`. |
+| Images in results | Each image is paired with JSON text that names the file path, so a model without vision still gets the result. Files also come as `resource_link`s, plus a `links` map in the JSON. |
+| Too many tools | `ANIMAROBO_TOOLSETS` (or `mcp --toolsets`) exposes only some groups. See [Toolsets](TOOLS.md#toolsets). |
+
+## Limits by client
+
+| Client | Tool limit | Tool-call timeout | Roots | Sampling | Uses annotations |
+|---|---|---|---|---|---|
+| Claude Code | None: tools are deferred and found by tool search | stdio: no per-call timer; calls are backgrounded after 2 min; 30 min idle limit | yes | n/a* | n/a* |
+| Claude Desktop | n/a* | about 60 s for local tools (user reports) | n/a* | n/a* | n/a* |
+| Cursor | Historically 40 across all servers; newer builds load tools lazily (unconfirmed) | about 60 s, not configurable (forum reports) | yes | no | n/a* |
+| Codex (CLI + IDE) | None; tool search for deferred tools | `tool_timeout_sec` (docs: default 60 s) | **no** | **no** | yes: read-only (or non-destructive and closed-world) tools skip approval |
+| VS Code Copilot | 128 tools per request | no default found | yes | yes (with consent) | yes: `readOnlyHint` skips confirmation |
+| Windsurf | 100 across all servers | n/a* | n/a* | n/a* | n/a* |
+| Gemini CLI | None | per-server `timeout`, default 10 min | yes | **no** | `readOnlyHint` for policies and Plan Mode |
+
+\*n/a: not documented by the client.
+
+With 62 tools, Animarobo fits every limit except Cursor's historic 40. In Cursor, if tools go
+missing, use `ANIMAROBO_TOOLSETS=core` (38 tools), or `marketing` / `video` if no other MCP
+servers are enabled.
+
+## Configuration
+
+### Claude Code
+
+```bash
+claude mcp add animarobo -s user -- npx -y animarobo mcp
+# or the plugin (server + workflow skill):
+#   /plugin marketplace add explorian006/animarobo
+#   /plugin install animarobo@animarobo
+```
+
+- **Startup:** with a cold `npx` cache, give it more time: `MCP_TIMEOUT=120000 claude`.
+- **Permissions:** run everything except destructive tools without prompts. The `allow`/`ask` snippet is in [TOOLS.md → Approval policies](TOOLS.md#approval-policies).
+- **Env vars:** add them with `-e KEY=value` on `claude mcp add`, or under `env` in `.mcp.json`.
+
+### Codex (CLI and IDE extension)
+
+`~/.codex/config.toml`, or a project `.codex/config.toml`:
+
+```toml
+[mcp_servers.animarobo]
+command = "npx"
+args = ["-y", "animarobo", "mcp"]
+startup_timeout_sec = 120     # first npx install
+tool_timeout_sec = 600        # synchronous previews; renders should use async anyway
+# env = { ANIMAROBO_TOOLSETS = "all", ANTHROPIC_API_KEY = "…" }
+# enabled_tools / disabled_tools = [...] to narrow the list
+```
+
+Or run `codex mcp add animarobo -- npx -y animarobo mcp`, then add the timeouts.
+
+- **Approvals:** in `auto` mode, read-only tools run without approval. To always ask before destructive tools, see [TOOLS.md](TOOLS.md#approval-policies) for the per-tool `approval_mode = "prompt"` blocks.
+- **Deliveries:** Codex has no roots, so `deliver` writes into the folder Codex started the server in (normally your project). Pass `dest` to choose another place.
+
+### Cursor
+
+`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{ "mcpServers": { "animarobo": {
+  "command": "npx", "args": ["-y", "animarobo", "mcp"],
+  "env": { "ANIMAROBO_TOOLSETS": "all" }
+} } }
+```
+
+Turn individual tools on or off in Cursor's MCP settings. Ask the agent to use `async: true` for
+renders, because Cursor's tool-call timeout (about 60 s) can't be changed.
+
+### VS Code (GitHub Copilot agent mode)
+
+`.vscode/mcp.json`, or `MCP: Open User Configuration`:
+
+```json
+{ "servers": { "animarobo": {
+  "type": "stdio", "command": "npx", "args": ["-y", "animarobo", "mcp"]
+} } }
+```
+
+Tools can be deselected under **Configure Tools**. `readOnlyHint` tools run without confirmation.
+
+### Claude Desktop
+
+`claude_desktop_config.json`: Settings → Developer → Edit Config. It lives in
+`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows and
+`~/.config/Claude/` on Linux. Restart the app after editing.
+
+```json
+{ "mcpServers": { "animarobo": { "command": "npx", "args": ["-y", "animarobo", "mcp"] } } }
+```
+
+Local tools are reported to time out after about 60 s, so ask for `async: true` on renders.
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`. Newer builds use `~/.config/devin/mcp_config.json`.
+
+```json
+{ "mcpServers": { "animarobo": { "command": "npx", "args": ["-y", "animarobo", "mcp"] } } }
+```
+
+Windsurf allows 100 tools across all servers. Hide tools with `"disabledTools": [...]`, or use
+`ANIMAROBO_TOOLSETS` in `env`.
+
+### Gemini CLI
+
+`~/.gemini/settings.json` (or project `.gemini/settings.json`):
+
+```json
+{ "mcpServers": { "animarobo": {
+  "command": "npx", "args": ["-y", "animarobo", "mcp"],
+  "timeout": 600000
+} } }
+```
+
+Or run `gemini mcp add animarobo npx -y animarobo mcp`. Narrow the list with
+`includeTools` / `excludeTools`. Don't rename the server to something with `_`, because Gemini's
+policy rules split names on it.
+
+### Cloud agents (Claude Code on the web, Codex cloud)
+
+Put the server entry in the repository's `.mcp.json` (Claude Code) or `.codex/config.toml`, and
+run `npx -y animarobo setup` in the environment's setup script. Deliveries
+land in the checkout. Commit them, or download them from the session.
+
+## Governance checklist for teams
+
+- **Pin a version:** use `animarobo@<version>` instead of `animarobo` (latest), so updates are deliberate.
+- **Expose only what a team needs:** `ANIMAROBO_TOOLSETS=marketing` for a social team, `core` for template-only work, `all,-director,-editor` to drop autonomous production.
+- **Keep destructive tools behind a prompt:** use the client snippets in [TOOLS.md](TOOLS.md#approval-policies). The destructive tools only touch Animarobo's own projects and brand kits; nothing deletes files outside `~/.animarobo` except `deliver`, which replaces its own previous delivery folder of the same name.
+- **Python execution is opt-in:** `manim_scene` runs agent-written Python, and only if Manim was installed with `setup --manim`. On a shared HTTP server it stays off unless `ANIMAROBO_ALLOW_MANIM=1`.
+- **Secrets are never echoed into tool results.** Provider keys (`ELEVENLABS_API_KEY`, `REPLICATE_API_TOKEN`, …) are read from the server's environment. Set them in the client's `env` block, not in prompts.
+- **Adding a tool:** declare it in `src/mcp/toolCatalog.ts` (group, read/write/destructive, idempotent, network, long-running) and run `npm run tools:doc`. The server refuses to start with an undeclared tool, and the tests check annotations, schema portability and that `TOOLS.md` is current.