@docyrus/animaguru 0.35.1 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/animaguru",
-  "version": "0.35.1",
+  "version": "0.38.0",
   "description": "Agent-friendly AnimaGuru CLI built with CrustJS",
   "type": "module",
   "bin": {

package/skills/animaguru/SKILL.md

@@ -17,7 +17,7 @@ Before creative work in a multi-animation workspace, select or create the intend
 
 Share the [animation-style gallery](https://animaguru.com/animation-styles), or open that URL in the internal browser when available, while asking the user to choose a style. Read the installed `animaguru.templates.json` for available styles and their skill names; `animaguru templates` lists the current CLI catalog. Offer the local catalog's choices so users select a skill actually installed in their workspace. Templates define appearance and motion; derive audience, message and story from the brief. Local scaffolding is separate from `projects create`, which creates a remote asset project. Never run `create` over an existing workspace.
 
-- Run `animaguru schema` for the installed command structure and flags, and `animaguru catalog` for styles, subject kinds, actions, asset types, models, video settings, and speech voices; `catalog --type music|speech|sfx|model|image|vector|video|sprites|avatars` prints one section. Use `--help` on a leaf command for details.
+- Run `animaguru schema` for the installed command structure and flags, and `animaguru catalog` for styles, subject kinds, actions, asset types, models, video settings, and speech voices; `catalog --type music|speech|sfx|model|image|vector|gif|video|sprites|avatars` prints one section. Use `--help` on a leaf command for details.
 - Check `animaguru auth status`, `animaguru workspaces list`, and `animaguru credits` before generation. If sign-in is needed, run `animaguru auth login --no-browser` and let the user approve the printed browser URL. Select the user's requested Personal or team workspace with `animaguru workspaces use personal|TEAM_ID` before listing or creating projects. Do not read or print stored credentials. Agent runners may inject `ANIMAGURU_TOKEN` and `ANIMAGURU_WORKSPACE` as secrets or configuration.
 - The default service is `https://animaguru.com`. Respect an existing `ANIMAGURU_URL` or pass `--url` to the leaf command when the user chooses another service. HTTP is supported only for loopback development.
 - `animaguru skills install [--dir PATH]` (CLI 0.28.0) installs every AnimaGuru and PixiJS skill, the latest published on animaguru.com, into `.claude/skills/` and `.agents/skills/` with `npx skills`, and records them in `skills-lock.json`; run it when the user wants the skills in a folder or refreshed. `npx skills update --project --yes` refreshes them later. In a workspace made by an older CLI, newer skills may name commands or kit helpers its code lacks, so suggest updating the workspace as well.
@@ -62,17 +62,38 @@ animaguru assets generate PROJECT_ID --type speech --name "Welcome" \
   --prompt "Welcome, traveler." --voice Kore --delivery "Warm and welcoming" --yes
 ```
 
-Images use the staff-managed route automatically. Use `--model` to select a model for video, music, speech or sound effects; discover the choices with `catalog` and the server's configured subset with `assets list`. Asset defaults are per type, independently of sprite project defaults. Image backgrounds are retained unless `--transparent` is supplied. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 image shapes. `--references SHA,SHA` (up to four) makes an image follow this project's saved images, uploads or sprite art. To keep a recurring character consistent, generate a character sheet once and reference its `file` SHA in every later image; refer to references in the prompt as Image 1, Image 2 and so on, and say what to take from each. `--aspect-ratio` is 1:1, 3:2, 2:3, 16:9 or 9:16; use 16:9 or 9:16 for video scenes. `--mask x,y,width,height[;…]` (up to eight rectangles, in fractions of Image 1 from the top left) edits only those parts of Image 1, the first reference, and keeps the rest and Image 1's shape. Look at the image before choosing the rectangles. Videos require an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, in the same project. Validate video options against the selected model's `videoProfiles` in `catalog`; omitted video settings use five seconds and that provider's first resolution/mode. MiniMax H3 Max and H3 Max Turbo (`fal/minimax-h3-max`, `fal/minimax-h3-max-turbo`) also take `--workflow text-to-video` (with `--aspect-ratio`) and `--workflow extend-video` (with `--source VIDEO_SHA`, 2K resolution, `--extend-output`, and up to three comma-separated `--audio-references`). From images, they accept `--end-reference` with or without `--reference` and a `--soundtrack AUDIO_SHA`. All workflows take `--prompt-expansion` and `--seed`. These need CLI 0.8.0 or newer. CLI 0.18.0 adds H3 Max's (not Turbo's) `--workflow reference-to-video` (keep a character across clips from up to nine `--references`, three `--reference-videos` and three `--audio-references`, named Image 1, Video 1, Audio 1 in the prompt; optional `--reference`, `--end-reference`, `--middle-reference` with `--middle-seconds`), `lip-sync` (the face in `--reference` says `--soundtrack` speech of 5 s–15 min; no `--prompt`; `--transcribe`), `camera-controls` (`--camera "time,azimuth,elevation,distance;…"`, 2–12 keyframes around `--reference`; without a prompt only the camera moves), `insert-video` (a 5–13 s scene inside `--source` from `--insert-at` to `--resume-at`, guided by `--references`/`--reference-videos`), `recast` (people in `--references` replace those in `--source`; pass `--subject-consent` only after each person agreed), `relight` (`--source` relit from a `--lighting` sphere image; no prompt), `3d-to-video` (a 3D render `--source` into footage, from `--references` or `--generated-references`) and `style` (`--style vhs|retro-toon-70s|low-poly|hand-drawn|16bit-pixel`, `--damage` for VHS, 768p, 5–15 whole seconds). Lip-sync, recast, relight and 3d-to-video take their input's length; their dry runs, like reference-to-video's and insert-video's, are server estimates because the price depends on the files. H3 takes fractional `--seconds` (6.5). CLI 0.21.0 adds FLUX 3 Max (`fal/flux-3-max`): image-to-video (with an optional `--end-reference`) and text-to-video for 5–20 whole seconds at 720p or 1080p with its own sound and no `--soundtrack`, and `--workflow keyframes-to-video`, which passes through 1–10 `--keyframes "SECONDS,SHA;…"` images, each reached at its second within `--seconds`. It always reasons about the prompt: `--prompt-expansion quality` thoroughly, other values lightly. CLI 0.30.0 adds HeyGen Video 1's (`heygen/heygen-video-1`) `--workflow text-to-video` (with `--aspect-ratio`) and `reference-to-video` (up to nine `--references`, three `--reference-videos`, of which it reads the first 5 s, and three `--audio-references`, named Image 1, Video 1, Audio 1 in the prompt; no `--reference`, `--end-reference` or `--middle-reference`), 1080p and 2K (16:9 or 9:16 from text or references), and `--seed`. From an image or text it runs to 30 whole seconds with `--prompt-expansion balanced` or `quality`, and every second past 15 costs more. For Gemini speech, `--prompt` is spoken verbatim and `--delivery` is a separate instruction. Music uses Lyria; the Gemini TTS models are for speech.
+Images use the staff-managed route automatically. Use `--model` to select a model for video, music, speech or sound effects; discover the choices with `catalog` and the server's configured subset with `assets list`. Asset defaults are per type, independently of sprite project defaults. Image backgrounds are retained unless `--transparent` is supplied. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 image shapes. `--references SHA,SHA` (up to four) makes an image follow this project's saved images, uploads or sprite art. To keep a recurring character consistent, generate a character sheet once and reference its `file` SHA in every later image; refer to references in the prompt as Image 1, Image 2 and so on, and say what to take from each. `--aspect-ratio` is 1:1, 3:2, 2:3, 16:9 or 9:16; use 16:9 or 9:16 for video scenes. `--mask x,y,width,height[;…]` (up to eight rectangles, in fractions of Image 1 from the top left) edits only those parts of Image 1, the first reference, and keeps the rest and Image 1's shape. Look at the image before choosing the rectangles. Videos require an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, in the same project. Validate video options against the selected model's `videoProfiles` in `catalog`; omitted video settings use five seconds and that provider's first resolution/mode. MiniMax H3 Max and H3 Max Turbo (`fal/minimax-h3-max`, `fal/minimax-h3-max-turbo`) also take `--workflow text-to-video` (with `--aspect-ratio`) and `--workflow extend-video` (with `--source VIDEO_SHA`, 2K resolution, `--extend-output`, and up to three comma-separated `--audio-references`). From images, they accept `--end-reference` with or without `--reference` and a `--soundtrack AUDIO_SHA`. All workflows take `--prompt-expansion` and `--seed`. These need CLI 0.8.0 or newer. CLI 0.18.0 adds H3 Max's (not Turbo's) `--workflow reference-to-video` (keep a character across clips from up to nine `--references`, three `--reference-videos` and three `--audio-references`, named Image 1, Video 1, Audio 1 in the prompt; optional `--reference`, `--end-reference`, `--middle-reference` with `--middle-seconds`), `lip-sync` (the face in `--reference` says `--soundtrack` speech of 5 s–15 min; no `--prompt`; `--transcribe`), `camera-controls` (`--camera "time,azimuth,elevation,distance;…"`, 2–12 keyframes around `--reference`; without a prompt only the camera moves), `insert-video` (a 5–13 s scene inside `--source` from `--insert-at` to `--resume-at`, guided by `--references`/`--reference-videos`), `recast` (people in `--references` replace those in `--source`; pass `--subject-consent` only after each person agreed), `relight` (`--source` relit from a `--lighting` sphere image; no prompt), `3d-to-video` (a 3D render `--source` into footage, from `--references` or `--generated-references`) and `style` (`--style vhs|retro-toon-70s|low-poly|hand-drawn|16bit-pixel`, `--damage` for VHS, 768p, 5–15 whole seconds). Lip-sync, recast, relight and 3d-to-video take their input's length; their dry runs, like reference-to-video's and insert-video's, are server estimates because the price depends on the files. H3 takes fractional `--seconds` (6.5). CLI 0.21.0 adds FLUX 3 Max (`fal/flux-3-max`): image-to-video (with an optional `--end-reference`) and text-to-video for 5–20 whole seconds at 720p or 1080p with its own sound and no `--soundtrack`, and `--workflow keyframes-to-video`, which passes through 1–10 `--keyframes "SECONDS,SHA;…"` images, each reached at its second within `--seconds`. It always reasons about the prompt: `--prompt-expansion quality` thoroughly, other values lightly. CLI 0.30.0 adds HeyGen Video 1's (`heygen/heygen-video-1`) `--workflow text-to-video` (with `--aspect-ratio`) and `reference-to-video` (up to nine `--references`, three `--reference-videos`, of which it reads the first 5 s, and three `--audio-references`, named Image 1, Video 1, Audio 1 in the prompt; no `--reference`, `--end-reference` or `--middle-reference`), 1080p and 2K (16:9 or 9:16 from text or references), and `--seed`. From an image or text it runs to 30 whole seconds with `--prompt-expansion balanced` or `quality`, and every second past 15 costs more. For Gemini speech, `--prompt` is spoken verbatim and `--delivery` is a separate instruction. Music uses Lyria (`lyria-3.5`, the default) or Mureka 9.5; the Gemini TTS models are for speech.
 
 For ElevenLabs speech, choose `eleven_v4` or `eleven_v4_turbo`, pass an ElevenLabs voice ID with `--voice` (George is the default), and put audio tags in `--prompt` rather than using `--delivery`. For sound effects, use `--type sfx`; the only model is `eleven_text_to_sound_v2`. SFX supports `--seconds` from 0.5 to 30 (default 5), `--loop`, and `--prompt-influence` from 0 to 1 (default 0.3). These additions require CLI 0.5.0 or newer; check `catalog` before using them with an installed CLI.
 
+CLI 0.36.0 adds Mureka 9.5 music on fal. `--model fal/mureka-9.5-song` sings `--lyrics` (up to 5,000 characters; tag sections `[Verse]`, `[Chorus]`) with `--vocals female|male`, and `--prompt` then sets the style (optional, up to 1,024 characters); without lyrics it writes the words from `--prompt` (up to 2,000 characters) in optional `--styles pop,rock,…` (`catalog --type music` lists them). `--seconds 120–300` asks for a length; otherwise Mureka chooses one, usually three to four minutes. A sung song costs 15 credits, one written from the prompt 50. `--model fal/mureka-9.5-instrumental` writes from `--prompt` alone (up to 1,024 characters, 15 credits). `--model fal/mureka-9.5-soundtrack --source SHA` scores a saved video (up to 100 MB), image or sprite art for 11 credits, with an optional mood `--prompt`; a video's soundtrack runs as long as the video, so score a finished cut, and an image gets a full-length track. Lyria takes none of these options and picks its own length. All of them return MP3.
+
+Seedance on BytePlus (`byteplus/seedance-2.5`, `byteplus/seedance-2.0`, `byteplus/seedance-2.0-fast`, `byteplus/seedance-2.0-mini`) films from `--reference` (optionally ending on `--end-reference`; the clip keeps the image's shape), from text (`--workflow text-to-video --aspect-ratio …`) or from saved images and audio (`--workflow reference-to-video`, up to nine `--references` and three `--audio-references`, named Image 1 and Audio 1 in the prompt; all but 2.5 need an image beside audio). It runs 4–15 whole seconds (2.5 up to 30) at 480p or 720p (2.0 also 1080p) with its own sound, and takes no `--soundtrack`, `--seed`, `--prompt-expansion`, reference videos or extensions. It refuses images of real people's faces, so use illustrated or generated art. It is charged the tokens BytePlus counts, never more than the dry run's estimate.
+
+HeyGen Voice (`heygen-voice-1`, or the faster and cheaper `heygen-voice-1-turbo`) speaks any of HeyGen's public voices: pass its ID with `--voice` (Nadine is the default; `catalog --type speech` lists `heygenVoices` to start from). It reads `--prompt` as written and detects the language, so it takes no `--delivery`; shape the read with punctuation and wording. It returns WAV and costs 1.5 credits per 1,000 characters, or 0.4 on Turbo.
+
 CLI 0.27.0 adds vectors: `--type vector` draws an editable SVG with Ideogram on fal (`fal/ideogram-vector`), for logos, icons, mascots and flat illustrations that must stay sharp at any size or move shape by shape. `--workflow text-to-vector` (default) draws `--prompt` at `--quality low|medium|high` (13, 16 or 20 credits; 32 at high with references), with `--aspect-ratio auto` (default) or 1:4–4:1, `--seed`, and up to five `--references` (this project's images or sprite art, the first leading, named Image 1… in the prompt). `--workflow image-to-vector --source IMAGE_SHA` traces a saved image or sprite for 10 credits, with `--shapes detailed|simple` and no `--prompt`; to vectorize a brand logo or a generated picture, save it as an image asset first. `--download` saves `NAME.svg`. Vectors can't be used as image or video references. Check `catalog --type vector` before using them with an installed CLI.
 
+CLI 0.38.0 adds a second vector model, GPT Image 2.6 (`--model fal/gpt-image-2.6-vector`). It draws from `--prompt` alone at `--quality low|medium|high`, with `--aspect-ratio auto` (default) or 1:3–3:1, and `--transparent` leaves out the background. It takes no `--references`, `--seed` or image-to-vector; use Ideogram to follow or trace an image. Its dry run holds 8, 12 or 22 credits by quality, and the job is charged the tokens fal meters.
+
 ```sh
 animaguru assets generate PROJECT_ID --type vector --name "Fox mascot" \
   --prompt "A friendly fox mascot waving, flat colors, bold clean outlines" --quality medium --dry-run
 animaguru assets generate PROJECT_ID --type vector --name "Logo" \
   --workflow image-to-vector --source IMAGE_SHA --shapes simple --dry-run
+animaguru assets generate PROJECT_ID --type vector --model fal/gpt-image-2.6-vector --name "Badge" \
+  --prompt "A round coffee shop badge, two flat colors" --transparent --dry-run
+```
+
+CLI 0.38.0 adds animated GIFs: `--type gif` draws a short loop with GPT Image 2.6 on fal, for a sprite's walk or idle cycle, an icon that moves or a sticker. `--prompt` is required; describe one motion that loops and say the subject stays the same in every frame. `--frames 2–16` (default 9), `--frame-ms 20–2000` per frame (default 200, rounded to 10), `--aspect-ratio 1:1|3:2|2:3|16:9|9:16` (default 1:1), `--quality low|medium|high` (default medium), `--transparent` for frames without a background, and up to four `--references` (this project's images, GIF stills or sprite art, named Image 1… in the prompt) to animate or follow. `--model fal/gpt-image-2.6-gif` (Flare, default) is faster and `fal/gpt-image-2.6-sunburst-gif` finer and slower. All frames share one 3840×2160 picture, so more frames are smaller: nine square frames are 960×960, sixteen 720×720 (`catalog --type gif` lists every size). The dry run holds credits at still-image prices for those frames (about 31 for the defaults); fal meters what is charged. `--download` saves `NAME.gif`. A GIF's `file` SHA, or its `preview` (a PNG of the first frame), works wherever a saved image does: a video's `--reference`, `--end-reference` or `--references`, an image's `--references`, a vector to trace, a 3D model's `--reference`. So to put a GIF in a generated video, pass its SHA as the frame or reference. In a film workspace, play the GIF itself with the kit's `gifClip()` (see `animaguru-video`). Check `catalog --type gif` before using GIFs with an installed CLI.
+
+```sh
+animaguru assets generate PROJECT_ID --type gif --name "Fox walk" \
+  --prompt "A cartoon fox walk cycle, side view, the same fox in every frame" --frames 8 --frame-ms 120 --transparent --dry-run
+animaguru assets generate PROJECT_ID --type gif --name "Fox wave" \
+  --prompt "The fox from Image 1 waves its paw, then holds still" --references CHARACTER_SHA --frames 6 --dry-run
+animaguru assets generate PROJECT_ID --type video --name "Fox walks off" \
+  --prompt "The fox walks out of the frame to the right" --reference GIF_SHA --dry-run
 ```
 
 CLI 0.28.0 adds 3D models: `--type model` builds a GLB from a saved image (`--reference SHA`, best) or from `--prompt` alone, with `--model tripo-h3.1` (default) or `hunyuan-3d-3.1-pro`, `--no-texture`, `--no-pbr` and `--faces`. `--rig` auto-rigs a humanoid character standing in a T- or A-pose, with `--animations idle,walk,wave` (named clips from `catalog --type model`, or Meshy library numbers; default idle,walk) and `--height` in metres. Downloads are `.glb`. CLI 0.35.0 adds `--model idol`: photoreal Gaussian splats of the object in a saved image (`--reference SHA`, required; `--photo` for a camera photo, `--splats`, `--seed`), downloaded as `.spz` and staged with the kit's `stage.splat()`. Read `animaguru-3d-models` before generating models or building 3D shots: it covers costs, rig limits (no fingers or facial blend shapes), when splats or meshes fit, optimisation and the kit's three.js stage.
@@ -96,7 +117,7 @@ animaguru files get PROJECT_ID references/ID/document.pdf --output references/le
 
 `jobs wait` tracks only the specified job. Drawing can queue follow-up animations: inspect `jobs list` and wait for the relevant jobs before exporting. A timeout or CLI exit does not cancel server work. CLI 0.32.0 adds `jobs cancel PROJECT_ID JOB_ID --yes`. A project runs its jobs one at a time; this cancels a queued job, or stops a running one at its next check on the provider, and the job fails with the reason. Credits it already spent stay spent, and a result the provider hasn't returned is lost. Use it when the user asks, or when one job is stuck and holds up the jobs behind it; never to hurry a job that is only slow. Inspect existing jobs before retrying a paid submission to avoid duplicate charges. Report failed jobs and their errors instead of repeatedly submitting the same work.
 
-`projects move PROJECT_ID --to OTHER_PROJECT_ID [--characters SLUG,SLUG] [--assets ASSET_ID] [--avatars GROUP_ID]` moves work between projects for free: characters with all their animations, saved assets and the project's own avatars. Use it to gather work into one project instead of regenerating it; it needs CLI 0.16.0.
+`projects move PROJECT_ID --to OTHER_PROJECT_ID [--characters SLUG,SLUG] [--assets ASSET_ID] [--avatars GROUP_ID]` moves work between projects for free: characters with all their animations, saved assets and, to a project in another workspace, the workspace's own avatars. Use it to gather work into one project instead of regenerating it; it needs CLI 0.16.0.
 
 `files get` downloads one file by its path from `files list`, such as an image, clip or PDF the user attached as a reference. `files export` downloads a ZIP. Both refuse to overwrite an existing file. Choose a fresh output path. Inspect the exported manifest and actual assets before integrating them into the game or app; use their real dimensions, frame ordering, and animation metadata.
 
@@ -143,6 +164,6 @@ Pro and Team accounts: `animaguru library search DESCRIPTION [--type sprite|imag
 Read these only when the task needs them:
 
 - `references/sprites.md`: animate, redraw or import sprite characters (`jobs submit` JSON).
-- `references/avatars.md`: HeyGen avatars and looks.
+- `references/avatars.md`: HeyGen avatars, looks, voices and avatar videos.
 - `references/sharing.md`: hosting on AnimaGuru (`submit`, `videos`) and uploading to YouTube. Making or exporting a film never authorizes sharing it.
 - `references/cloud.md`: cloud sync, versions and cloning.

package/skills/animaguru/references/avatars.md

@@ -4,7 +4,7 @@ Read from the `animaguru` skill only when the user wants a HeyGen avatar.
 
 ## HeyGen avatars
 
-CLI 0.13.0 adds `avatars`. Check `animaguru avatars --help` before using it with an installed CLI. A group is a character, its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. `avatars list PROJECT_ID` browses HeyGen's public catalog from any project; `--ownership private` lists the avatars this project created, which only it can see or change. `avatars looks PROJECT_ID --group GROUP_ID` lists a character's looks, and `avatars templates` lists Look Pack and look template IDs.
+CLI 0.13.0 adds `avatars`, and 0.37.0 adds `avatars video` and `avatars voices`. Check `animaguru avatars --help` before using it with an installed CLI. A group is a character, its looks are outfits, poses or styles, and a look ID is what HeyGen renders with. `avatars list PROJECT_ID` browses HeyGen's public catalog from any project; `--ownership private` lists the avatars of the project's workspace. Every project in that workspace can use them, and no other workspace can see, change or render them. `avatars looks PROJECT_ID --group GROUP_ID` lists a character's looks, and `avatars templates` lists Look Pack and look template IDs.
 
 ```sh
 animaguru avatars create PROJECT_ID --type prompt --name "Ada" \
@@ -19,4 +19,17 @@ animaguru avatars wait PROJECT_ID LOOK_ID
 
 `--file` and `--reference-images` take a project file SHA, an HTTPS URL (up to 32 MB) or a local file (up to 8 MB). Photos and footage show a real person: pass `--subject-consent` only after the user confirms that person agreed to become an avatar, and do not make avatars of people the user has no permission to depict. A `digital_twin` trains on about two minutes of footage and also needs the person's own consent: run `avatars consent PROJECT_ID GROUP_ID`, give them the 24-hour link, and check `consentStatus` with `avatars get PROJECT_ID --group GROUP_ID`.
 
-Avatars and looks are charged when HeyGen accepts them and need `--yes`; get the estimate with `--dry-run` first. New looks start `processing`: use `avatars wait` rather than creating them again. `avatars rename`, `avatars voice` (default voice) and `avatars delete --yes` change only the project's own avatars; deletion is permanent, so run it only when the user asks to delete that avatar.
+Avatars and looks are charged when HeyGen accepts them and need `--yes`; get the estimate with `--dry-run` first. New looks start `processing`: use `avatars wait` rather than creating them again. `avatars rename`, `avatars voice` (default voice) and `avatars delete --yes` change only the workspace's own avatars; deletion is permanent and also deletes the voice cloned for a digital twin, so run it only when the user asks to delete that avatar.
+
+## Avatar videos
+
+`avatars video` makes a video of one completed look (the workspace's or a public one) and saves it to the project as a video asset. Give `--script` (or `--script-file`, up to 1,500 characters) for the avatar to speak, or `--audio SHA` for saved speech or music to lip-sync, up to 120 seconds. Without `--voice` a script uses the look's own voice; `avatars voices PROJECT_ID --language Turkish` lists public voices, and `--ownership private` the voices cloned from the workspace's digital twins. Voices cloned for another workspace are refused. `--model` picks the engine (`heygen/avatar-iv` by default, `heygen/avatar-v`, `heygen/avatar-iii`) and must be in the look's `supportedEngines`. A digital twin renders only once its subject's consent is accepted.
+
+```sh
+animaguru avatars video PROJECT_ID --look LOOK_ID --name "Welcome" \
+  --script "Hi, I'm Ada. Here is what we shipped this week." --dry-run
+animaguru avatars video PROJECT_ID --look LOOK_ID --name "Voice-over cut" --audio SPEECH_SHA --yes
+animaguru jobs wait PROJECT_ID JOB_ID
+```
+
+The dry run asks the server, which checks the look, voice and audio and measures the audio's length. The video is charged for the seconds HeyGen makes; wait for the returned job with `jobs wait` and find the video with `assets list`.

package/skills/animaguru/references/sharing.md

@@ -16,9 +16,9 @@ animaguru videos list --scope shared
 animaguru videos get VIDEO_ID
 ```
 
-Submissions default to private. `--share` is a comma-separated list of verified AnimaGuru account emails; selected viewers sign in to watch. `--visibility public` lists the animation at [Videos](https://animaguru.com/videos) and permits anyone to watch, download its export, and embed an HTML5 player. Choose the audience from the user's request; a request to make or export a film alone does not authorize sharing it. `--yes` acknowledges the upload and selected audience, and spends no generation credits.
+Submissions default to private. `--share` is a comma-separated list of verified AnimaGuru account emails; AnimaGuru emails each selected viewer the watch link once the upload finishes, and they sign in to watch. `--visibility public` lists the animation at [Videos](https://animaguru.com/videos) and permits anyone to watch, download its export, and embed an HTML5 player. Choose the audience from the user's request; a request to make or export a film alone does not authorize sharing it. `--yes` acknowledges the upload and selected audience, and spends no generation credits.
 
-The JSON result returns the video ID and watch URL. Owners manage details and recipients on that page, or run `animaguru videos share VIDEO_ID --visibility private --share "reviewer@example.com" --yes`; this replaces the entire recipient list. Public sharing uses `--visibility public` without `--share`. Removing a recipient or making a public film private blocks previous playback URLs immediately. `animaguru videos poster VIDEO_ID --file production/exports/film.jpg --yes` replaces the poster of an uploaded video with a PNG, JPEG or WebP up to 2 MiB, such as the designed thumbnail the MP4 export saves. A public video's new poster goes back to staff review and the video is hidden from the public until it is approved, so tell the user before replacing it. `animaguru videos delete VIDEO_ID --yes` removes the hosted files.
+The JSON result returns the video ID and watch URL. Owners manage details and recipients on that page, or run `animaguru videos share VIDEO_ID --visibility private --share "reviewer@example.com" --yes`; this replaces the entire recipient list, and AnimaGuru emails the link to each newly added recipient (once per video, so re-adding someone sends nothing). Public sharing uses `--visibility public` without `--share`. Removing a recipient or making a public film private blocks previous playback URLs immediately. `animaguru videos poster VIDEO_ID --file production/exports/film.jpg --yes` replaces the poster of an uploaded video with a PNG, JPEG or WebP up to 2 MiB, such as the designed thumbnail the MP4 export saves. A public video's new poster goes back to staff review and the video is hidden from the public until it is approved, so tell the user before replacing it. `animaguru videos delete VIDEO_ID --yes` removes the hosted files.
 
 `videos list` shows the selected workspace's library; add `--workspace personal` or `--workspace TEAM_ID` for another (CLI 0.20.0). When the user asks to move videos between their personal library and a team, run `animaguru videos move VIDEO_ID… --workspace TEAM_ID --yes` (or `--workspace personal`). Moving keeps each video's ID, links, subtitles, recipients and review, and every team member can watch it, so move only videos the user names. A video made from a project's animation stays with its project: the user transfers the project to the team on the website first. If one video can't be moved, the command stops and reports `moved`, `error` and `notMoved`; fix the cause, then rerun it with the same IDs, since a video already in the target library is left as it is.
 

package/skills/animaguru-video/SKILL.md

@@ -81,6 +81,7 @@ Build on the shared kit instead of re-implementing helpers: `src/kit/` in a stan
 - Motion: `win`, `inOut`, `easeOut`/`easeIn`/`easeInOut`/`easeBack`, `bump`, `lerp`, `mixColor`, `hex`, seeded `rng`, `show`, `setText`.
 - Text and fonts: `txt(value, size, { family: "heading" | "body" | "mono", weight, fill, … })`, `useBrandFonts(branding, monoFamily?)`, `loadFonts([{ family, url }])` (variable fonts get their weight range), `gradientFill(colors)`.
 - Drawing: `panel`, `partialLine`, `bezier`, `pointAt`, `check`, `cross`, `person`, `glowTexture`, `vignetteTexture`, `rasterSvg` (exact-width logo textures), `Badge`, `Pill`.
+- GIFs: `gifClip(url, { loop, speed, scaleMode })` from `kit/gif` (kept out of the index), an animated GIF as a sprite on the film clock. See [GIFs](#gifs).
 - Layout: `safeArea(config)` and `stack(nodes, { x, y, gap })`. Set `"safeArea": "reels"` (or `{ top, right, bottom, left }` pixels) in `film.config.json` for vertical social films; review checks text against it.
 
 Keep `src/film.ts` to setup and the scene list, and put each scene in `src/scenes/NAME.ts` as `export function hook(film: FilmBase, cue: CueSheet) { … }` that adds to `film.world` and calls `film.on`. Write and fix one scene file at a time with targeted edits rather than rewriting the whole film. Claude Code's Write tool refuses to replace a file that has not been opened with Read in this session (`cat` does not count), so Read the starter `src/film.ts` before replacing it.
@@ -95,7 +96,24 @@ Pro and Team accounts can take ready-made music, sound effects, voice-overs, cli
 
 ## Vectors
 
-Logos, icons and flat mascots can be generated as SVG (`animaguru assets generate PROJECT_ID --type vector …`, see the `animaguru` skill) or traced from a saved image (`--workflow image-to-vector`), then saved into the film with `--download public/assets/`. Draw one with the kit's `rasterSvg(url, width)` at the width it appears on screen, so it stays sharp; for shapes that scale or move separately, load it as geometry with `Assets.load({ src, data: { parseAsGraphicsContext: true } })` and `new Graphics(context)` (see `pixijs-assets`). Ask for `--shapes simple` or `--quality low` when the art will be small or animated part by part.
+Logos, icons and flat mascots can be generated as SVG (`animaguru assets generate PROJECT_ID --type vector …`, see the `animaguru` skill) or traced from a saved image (`--workflow image-to-vector`), then saved into the film with `--download public/assets/`. Ideogram (the default) can follow reference images; `--model fal/gpt-image-2.6-vector` draws from the prompt alone and takes `--transparent`, so the art comes without a background to place over a scene. Draw one with the kit's `rasterSvg(url, width)` at the width it appears on screen, so it stays sharp; for shapes that scale or move separately, load it as geometry with `Assets.load({ src, data: { parseAsGraphicsContext: true } })` and `new Graphics(context)` (see `pixijs-assets`). Ask for `--shapes simple` or `--quality low` when the art will be small or animated part by part.
+
+## GIFs
+
+A GIF asset (`animaguru assets generate PROJECT_ID --type gif …`, see the `animaguru` skill) is a short looping animation drawn by GPT Image 2.6: a character's walk or idle cycle, a waving mascot, a spinning coin, a blinking icon. Pass a saved image or sprite art as `--references` to animate that exact character, and `--transparent` for frames without a background to place over a scene. Save it into the film with `--download public/assets/`.
+
+Never play a GIF with an `<img>` or a GifSprite that runs on its own: it would follow the wall clock, so seeking, review frames and the MP4 export would show other frames than the preview. Load it with the kit's `gifClip` and drive it from the scene's update:
+
+```ts
+import { gifClip } from "../kit/gif"; // workspace: "../../../../runtime/kit/gif" from src/scenes/
+
+const fox = await gifClip(publicAsset("assets/fox-wave.gif"), { scaleMode: "nearest" }); // nearest keeps pixel art crisp
+fox.sprite.anchor.set(0.5, 1); fox.sprite.position.set(960, 900);
+film.world.addChild(fox.sprite);
+film.on((t) => { fox.at(t - 4.2); fox.sprite.visible = t >= 4.2; });
+```
+
+`at(seconds)` shows the frame for that moment of the GIF from its own frame timings, looping unless `{ loop: false }` (then it holds the last frame); `speed` plays it faster or slower, and `frames`/`duration` give its length. Move, scale and fade the sprite with the usual motion helpers while it plays. Each frame is a separate texture, so keep a film to a few GIFs; for a long or many-frame cycle use a sprite sheet with `AnimatedSprite` instead. A GIF can also open an AI clip: its file SHA works as `--reference` for `assets generate --type video` (the server uses its first frame).
 
 ## Voiceover, music and captions
 

package/templates/video/src/kit/gif.ts

@@ -0,0 +1,40 @@
+import { Assets } from "pixi.js";
+import { GifSprite, type GifSource } from "pixi.js/gif";
+
+/*
+  Animated GIFs on the film's clock. Import from "./kit/gif" (standalone) or "../../../runtime/kit/gif"
+  (workspace animation); it is kept out of the kit's index so films without a GIF don't load the
+  GIF decoder.
+*/
+
+export type GifClip = {
+  /** A Sprite showing the frame `at` chose; position, scale and anchor it like any sprite. */
+  sprite: GifSprite;
+  /** How many frames the GIF has, and how long one loop plays in seconds. */
+  frames: number;
+  duration: number;
+  /** Shows the frame for `seconds` into the GIF (pass `t - start` from the scene's update). */
+  at: (seconds: number) => void;
+};
+
+/**
+  Loads an animated GIF, such as an AnimaGuru GIF asset (a sprite's walk cycle, a moving icon), as a
+  sprite that never plays by itself: each update calls `at`, which picks the frame from the GIF's own
+  frame timings. Preview, seeking, review frames and MP4 export then show the same frame at the same
+  moment. It loops unless `loop` is false, when it holds its last frame; `speed` scales its timing.
+  Pixel-art GIFs stay crisp with `scaleMode: "nearest"`.
+*/
+export async function gifClip(url: string, { loop = true, speed = 1, scaleMode }: { loop?: boolean; speed?: number; scaleMode?: "linear" | "nearest" } = {}): Promise<GifClip> {
+  const source = await Assets.load<GifSource>(scaleMode ? { src: url, data: { scaleMode } } : url);
+  const sprite = new GifSprite({ source, autoPlay: false, autoUpdate: false, loop });
+  const last = source.totalFrames - 1;
+  const at = (seconds: number) => {
+    const ms = Math.max(0, seconds * speed * 1000);
+    if (!loop && ms >= source.duration) { sprite.currentFrame = last; return; }
+    const time = ms % source.duration;
+    const index = source.frames.findIndex((frame) => time >= frame.start && time < frame.end);
+    sprite.currentFrame = index === -1 ? last : index;
+  };
+  at(0);
+  return { sprite, frames: source.totalFrames, duration: source.duration / 1000, at };
+}