@docyrus/animaguru 0.16.2 → 0.17.0

package/package.json

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

package/skills/animaguru/SKILL.md

@@ -37,7 +37,7 @@ Generation and reference imports spend credits and require `--yes`. Use it for w
 
 CLI/API balances, estimates, credit ranges and queued-job receipts use AnimaGuru credits, including fractional amounts such as 0.7. This includes offline `--dry-run` estimates. Compare them directly with the user's credit budget; do not rescale returned amounts or convert credits into currency.
 
-`generate`, `jobs submit`, and `files import` accept optional `--image-model` and `--video-model` flags. These select models for that operation and its explicitly queued animations. Use `animaguru models PROJECT_ID --image-model IMAGE_ID --video-model VIDEO_ID` only when the user wants to change defaults for future jobs. Omitted selections use project defaults, then service defaults. Discover available identifiers from `catalog` rather than hardcoding model names.
+Image generation uses staff-managed main and backup routes. Do not choose or send an image model. `generate`, `jobs submit`, and `files import` accept `--video-model` for video selection. Use `animaguru models PROJECT_ID --video-model VIDEO_ID` only when the user wants to change the video default. Discover video identifiers from `catalog`.
 
 ## Standalone images, video, music and speech
 
@@ -46,6 +46,12 @@ CLI 0.4.0 adds `assets generate`, `assets submit`, `assets list`, and `assets do
 ```sh
 animaguru assets generate PROJECT_ID --type image --name "Forest" \
   --prompt "A moonlit watercolor forest" --aspect-ratio 3:2 --yes
+animaguru assets generate PROJECT_ID --type image --name "Marie in the lab" \
+  --prompt "Marie from Image 1, same face, hair and coat, at her lab bench" \
+  --references CHARACTER_SHEET_SHA --aspect-ratio 16:9 --yes
+animaguru assets generate PROJECT_ID --type image --name "Marie, night" \
+  --prompt "Replace the window view with a starry night sky" \
+  --references SCENE_SHA --mask 0.5,0,0.5,1 --yes
 animaguru assets generate PROJECT_ID --type video --name "Forest breeze" \
   --prompt "Leaves drift slowly in the breeze" --reference IMAGE_BLOB_SHA \
   --seconds 5 --resolution 768p --mode quality --yes
@@ -55,11 +61,11 @@ animaguru assets generate PROJECT_ID --type speech --name "Welcome" \
   --prompt "Welcome, traveler." --voice Kore --delivery "Warm and welcoming" --yes
 ```
 
-Use `--model` to select a model for any asset type; 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. 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. 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. For Gemini speech, `--prompt` is spoken verbatim and `--delivery` is a separate instruction. Music uses Lyria; 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.
 
-Use `--dry-run` for local request validation and estimated credits without sign-in or paid work. The estimate does not prove the server has the provider, the credits, or the reference image. Use `--yes` only within the user's existing spending authorization. For file-based requests, write the API asset request as JSON and use `assets submit PROJECT_ID --file asset.json --yes`; `--model` overrides the file's selection.
+Use `--dry-run` for local request validation and estimated credits without sign-in or paid work. The estimate does not prove the server has the provider, the credits, or the reference image. Use `--yes` only within the user's existing spending authorization. For file-based requests, write the API asset request as JSON and use `assets submit PROJECT_ID --file asset.json --yes`; `--model` overrides the file's selection for non-image assets. Image model fields in old files are ignored.
 
 Add `--download PATH` to `assets generate` or `assets submit` to wait for the job and save the result in one call; a folder PATH (existing or ending in `/`) receives `NAME.EXT`, and existing files are never overwritten. `--wait` waits without downloading; `--timeout` sets the limit (default 600 s). For several assets, such as one speech file per voiceover line, write `{"defaults": {"type": "speech", "model": "…", "voice": "…", "delivery": "…"}, "assets": [{"name": "vo-01-hook", "prompt": "…"}]}` and run `assets batch PROJECT_ID --file lines.json --dry-run`, then `--yes --download production/audio/vo/`. Every item is validated before anything is submitted. If a submission fails, the batch stops and prints the receipts already submitted; check those (and `jobs list`) instead of resubmitting. Older CLIs lack these flags: check `--help`, and otherwise use `jobs wait PROJECT_ID JOB_ID`, read the asset id from `assets list` and download with `assets download PROJECT_ID ASSET_ID --output welcome.wav`, or export the complete project ZIP.
 
@@ -73,13 +79,14 @@ animaguru jobs list PROJECT_ID
 animaguru projects get PROJECT_ID
 animaguru files list PROJECT_ID
 animaguru files export PROJECT_ID --output forest-cast.zip
+animaguru files get PROJECT_ID references/ID/document.pdf --output references/lesson.pdf
 ```
 
 `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. 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.
 
-`files export` downloads a ZIP and refuses 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.
+`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.
 
 ## Shared workspace commands
 
@@ -95,6 +102,10 @@ For hosting, run `animaguru submit animations/NAME --yes`, or `animaguru submit
 
 Pro and Team accounts: `animaguru library search DESCRIPTION [--type sprite|image|video|music|speech|sfx] [--labels a,b]` finds ready-made assets; `animaguru library import ID --project PROJECT_ID` copies one into a project and `animaguru library download ID --output DIR` saves its files. Search it before generating common assets (whooshes, background music, stock clips, characters); importing spends no credits.
 
+## Saved brand kits
+
+`animaguru brands list` lists brands in the selected cloud workspace; `brands get BRAND_ID` reads a kit. Before researching a shared identity, check for the user's saved brand. `brands download BRAND_ID --output WORKSPACE_ROOT` installs its `branding/` files for films; inspect its guide and logo, and use `--force` only when replacing the local kit is intended. Create one with `brands create --name NAME` (or `--file FIELDS.json`), or `brands research OFFICIAL_HTTPS_URL` for a user-supplied website; poll `brands get` until `ready` or `failed`. `brands upload BRAND_ID --file logo.svg --kind logo --yes` uploads an image, then `brands update BRAND_ID --file PATCH.json` can set `{"logo":"bf_…"}` or `{"assets":["bf_…"]}` using returned IDs. Preserve existing asset IDs when extending that list. Pass `--workspace personal` or a team ID to list/create/research for an explicit cloud workspace.
+
 ## On demand
 
 Read these only when the task needs them:

package/skills/animaguru/references/cloud.md

@@ -6,7 +6,7 @@ Read from the `animaguru` skill only when the user asks for cloud sync, versions
 
 CLI 0.11.0 adds `animaguru cloud` for users on Individual Pro or Team. Discover it in `animaguru schema`. Commands run from anywhere inside a video workspace; `--dir PATH` selects another folder.
 
-Only link a folder when the user asks for cloud sync. `cloud link` creates a cloud project in the selected AnimaGuru workspace (`workspaces use` picks a team), and `cloud link --id PROJECT_ID` attaches an existing one. In a linked folder:
+Only link a folder when the user asks for cloud sync. A folder syncs with one AnimaGuru project's animations, shown on that project's Animations tab in the studio. `cloud link --project PROJECT_ID` syncs with an existing project (`prj_…`); without it, `cloud link` creates a new project named after the folder (or `--name`) in the selected AnimaGuru workspace (`workspaces use` picks a team). In a linked folder:
 
 - Check `cloud status` before ending a working session.
 - Save with `cloud push -m "MESSAGE"` at milestones the user would want to return to, such as an approved storyboard, finished scenes or an exported cut. Describe the change in the message.
@@ -14,6 +14,6 @@ Only link a folder when the user asks for cloud sync. `cloud link` creates a clo
 - When push reports a newer cloud version, run `cloud pull`.
 - When pull stops on files changed on both sides, show them to the user. Ask before using `--prefer local` (keep theirs; the next push replaces the cloud copy) or `--prefer cloud` (take the cloud's; local copies go to `.animaguru/sync/backups/`).
 
-`cloud versions` lists history. `cloud restore VERSION [--path P]` brings back an earlier version without rewriting history; then push to save it as the newest version. Restore refuses to replace unsaved changes unless `--yes`, and needs the user's go-ahead. `cloud clone PROJECT_ID DIR` downloads a project; run `npm install` there. `cloud delete PROJECT_ID --yes` permanently removes every version: run it only when the user asks to delete that cloud project.
+`cloud versions` lists history. `cloud restore VERSION [--path P]` brings back an earlier version without rewriting history; then push to save it as the newest version. Restore refuses to replace unsaved changes unless `--yes`, and needs the user's go-ahead. `cloud clone PROJECT_ID DIR` downloads a project; run `npm install` there. `cloud list` lists projects with synced animations. `cloud delete PROJECT_ID --yes` permanently removes the project's animations: every version, Animator draft and stored file, while the project and its assets stay. Run it only when the user asks to delete those animations.
 
 Sync never uploads node_modules, exports, frames, `.env` files, credentials, keys, links or `.gitignore`/`.animaguruignore` matches. Add bulky regenerable files to `.animaguruignore` rather than deleting them. Images, video, audio and ZIP files are stored once in cloud storage at any size and count toward the plan's media storage (20 GB Pro, 100 GB per Team). Every other file is versioned in Git. A work file over 32 MB stops the push: tell the user, and ignore or move it only with their agreement. If the plan ended, pushing is refused, but pulling and cloning still work. Never read or print `.animaguru/sync/` tokens; the CLI requests short-lived Git credentials itself.

package/skills/animaguru-video/SKILL.md

@@ -79,7 +79,7 @@ Before choreographing a scene from scratch, search the AnimaGuru motion library
 
 ## Asset library
 
-Pro and Team accounts can take ready-made music, sound effects, voice-overs, clips, images and sprites from the AnimaGuru asset library instead of generating them: `animaguru library search DESCRIPTION --type music|sfx|speech|video|image|sprite` (natural language and keywords). `animaguru library download ID --output public/assets/` saves a file into the film (sprites save their sheets with `animation.json` frame rectangles and timing); `animaguru library import ID --project PROJECT_ID` adds it to a cloud project instead. Prefer a library whoosh or background track over generating one; it spends no credits.
+Pro and Team accounts can take ready-made music, sound effects, voice-overs, clips, images and sprites from the AnimaGuru asset library instead of generating them: `animaguru library search DESCRIPTION --type music|sfx|speech|video|image|sprite` (natural language and keywords). `animaguru library download ID --output public/assets/` saves a file into the film (sprites save their sheets with `animation.json` frame rectangles and timing); `animaguru library import ID --project PROJECT_ID` adds it to an AnimaGuru project's assets instead. Prefer a library whoosh or background track over generating one; it spends no credits.
 
 ## Voiceover, music and captions
 
@@ -117,7 +117,7 @@ When the user requests hosting or sharing, use `animaguru submit --yes` from thi
 
 ## Cloud versions
 
-If the workspace has `.animaguru/sync/link.json`, it syncs with an AnimaGuru cloud project. Save milestones the user would want to return to with `animaguru cloud push -m "MESSAGE"`, such as an approved brief, finished scenes or a delivered export. Run `animaguru cloud pull` when push reports a newer version. Do not link a folder or delete a cloud project unless the user asks. Read the local AnimaGuru skill's cloud section for conflicts, restores and plan rules.
+If the workspace has `.animaguru/sync/link.json`, it syncs with an AnimaGuru project's animations. Save milestones the user would want to return to with `animaguru cloud push -m "MESSAGE"`, such as an approved brief, finished scenes or a delivered export. Run `animaguru cloud pull` when push reports a newer version. Do not link a folder or delete a project's animations unless the user asks. Read the local AnimaGuru skill's cloud section for conflicts, restores and plan rules.
 
 ## Multi-animation workspace
 

package/templates/video/AGENTS.md

@@ -36,4 +36,4 @@ When asked to host or share the finished film, read the local AnimaGuru skill's
 
 ## Cloud versions
 
-A linked folder has `.animaguru/sync/link.json`. Save milestones the user would want to return to with `animaguru cloud push -m "MESSAGE"`; run `animaguru cloud pull` when push reports a newer cloud version. Ask before resolving files changed on both sides, restoring over unsaved work, linking a new folder or deleting a cloud project. The AnimaGuru skill's cloud section has the details.
+A linked folder has `.animaguru/sync/link.json`. Save milestones the user would want to return to with `animaguru cloud push -m "MESSAGE"`; run `animaguru cloud pull` when push reports a newer cloud version. Ask before resolving files changed on both sides, restoring over unsaved work, linking a new folder or deleting a project's animations. The AnimaGuru skill's cloud section has the details.

package/templates/video/README.md

@@ -104,4 +104,4 @@ After signing in with `animaguru auth login`, run `animaguru submit --yes` here
 
 ## Cloud versions
 
-On Individual Pro or Team, `animaguru cloud link` creates a cloud project for this folder. `animaguru cloud push -m "What changed"` then saves a version, `animaguru cloud pull` brings in versions saved elsewhere, and `animaguru cloud clone PROJECT_ID` continues on another computer. `animaguru cloud restore VERSION` returns to an earlier version; push afterwards to keep it. Dependencies, exports, frames, `.env` files, credentials and anything in `.gitignore` or `.animaguruignore` stay local. The studio's Cloud page lists every version and its files.
+On Individual Pro or Team, `animaguru cloud link` syncs this folder with a new AnimaGuru project, or with an existing one through `--project PROJECT_ID`. `animaguru cloud push -m "What changed"` then saves a version, `animaguru cloud pull` brings in versions saved elsewhere, and `animaguru cloud clone PROJECT_ID` continues on another computer. `animaguru cloud restore VERSION` returns to an earlier version; push afterwards to keep it. Dependencies, exports, frames, `.env` files, credentials and anything in `.gitignore` or `.animaguruignore` stay local. The project's Animations tab in the studio lists every version and its files.

package/templates/video/scripts/audio-mix.mjs

@@ -13,9 +13,10 @@ const RATE = 48000;
 export const MIX_DEFAULTS = { musicDb: -9, duck: { threshold: 0.03, ratio: 6, attack: 20, release: 350 }, loudness: { i: -14, tp: -2, lra: 9 } };
 
 /** The music part of the graph for input `input`, as edited by audio:music (a trim or a bar-aligned cut). */
+// Padding counts samples at RATE: the bundled Linux ffmpeg (@ffmpeg-installer) has no apad whole_dur option.
 export function musicGraph(edit, { input = 0, duration, musicDb = MIX_DEFAULTS.musicDb, label = "music" }) {
   const headIn = Math.max(0, Number(edit?.headIn ?? 0)), fadeIn = Number(edit?.fadeIn ?? (headIn > 0.05 ? 0.25 : 0.02)), fadeOut = Number(edit?.fadeOut ?? 0.6);
-  const ending = `atrim=0:${duration},apad=whole_dur=${duration},afade=t=out:st=${round(Math.max(0, duration - fadeOut))}:d=${fadeOut},volume=${musicDb}dB,aformat=sample_fmts=fltp:sample_rates=${RATE}:channel_layouts=stereo[${label}]`;
+  const ending = `atrim=0:${duration},apad=whole_len=${Math.round(duration * RATE)},afade=t=out:st=${round(Math.max(0, duration - fadeOut))}:d=${fadeOut},volume=${musicDb}dB,aformat=sample_fmts=fltp:sample_rates=${RATE}:channel_layouts=stereo[${label}]`;
   if (edit?.type === "cut") {
     const crossfade = Number(edit.crossfade ?? 0.02), cutA = Number(edit.cutA), cutB = Number(edit.cutB);
     if (!(cutA > headIn) || !(cutB >= 0)) throw new Error("A music cut needs cutA after headIn and a non-negative cutB.");
@@ -37,7 +38,7 @@ export function mixGraph({ music, vo, edit, duration, musicDb = MIX_DEFAULTS.mus
   if (music) filters.push(...musicGraph(edit, { input: 0, duration, musicDb }));
   if (vo) {
     // Mono VO, a little presence and gentle compression, centred in stereo.
-    filters.push(`[${voInput}:a]aresample=${RATE},aformat=channel_layouts=mono,highpass=f=80,equalizer=f=3200:t=q:w=1.2:g=2,acompressor=threshold=-20dB:ratio=3:attack=5:release=120:makeup=3dB,pan=stereo|c0=c0|c1=c0,aformat=sample_fmts=fltp:channel_layouts=stereo,apad=whole_dur=${duration},atrim=0:${duration}${music ? ",asplit=2[vo][key]" : "[mix]"}`);
+    filters.push(`[${voInput}:a]aresample=${RATE},aformat=channel_layouts=mono,highpass=f=80,equalizer=f=3200:t=q:w=1.2:g=2,acompressor=threshold=-20dB:ratio=3:attack=5:release=120:makeup=3dB,pan=stereo|c0=c0|c1=c0,aformat=sample_fmts=fltp:channel_layouts=stereo,apad=whole_len=${Math.round(duration * RATE)},atrim=0:${duration}${music ? ",asplit=2[vo][key]" : "[mix]"}`);
   }
   if (music && vo) {
     filters.push(`[music][key]sidechaincompress=threshold=${duck.threshold}:ratio=${duck.ratio}:attack=${duck.attack}:release=${duck.release}:makeup=1[ducked]`);

package/templates/video/scripts/audio-vo.mjs

@@ -140,7 +140,7 @@ async function main() {
       labels.push(label);
     }
   }
-  filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0,apad=whole_dur=${duration},atrim=0:${duration}[out]`);
+  filters.push(`${labels.join("")}amix=inputs=${labels.length}:normalize=0,apad=whole_len=${Math.round(duration * SAMPLE_RATE)},atrim=0:${duration}[out]`);
   const work = path.join(base, "production/audio/work");
   await mkdir(work, { recursive: true });
   const track = path.join(work, "vo-track.wav");