@docyrus/animaguru 0.16.2 → 0.18.0

package/README.md

@@ -114,7 +114,7 @@ animaguru files list PROJECT_ID
 animaguru files export PROJECT_ID --output forest-cast.zip
 ```
 
-`jobs wait` waits for the specified job only. A drawing may queue follow-up animation jobs; inspect `jobs list` and wait for those before exporting. Jobs continue on the server if the CLI exits. `files export` refuses to overwrite a file. `projects rename PROJECT_ID --name "New name"` and `projects delete PROJECT_ID --yes` manage the library. `projects move PROJECT_ID --to OTHER_PROJECT_ID --characters SLUG,SLUG --assets ASSET_ID --avatars GROUP_ID` moves characters (with all their animations), saved assets and the project's own avatars to another project you can write to, without regenerating anything (CLI 0.16.0). `models PROJECT_ID --image-model gpt-image-2.5 --video-model heygen/heygen-video-1` sets the defaults for future jobs. The previous `--model` option remains an alias for `--image-model`.
+`jobs wait` waits for the specified job only. A drawing may queue follow-up animation jobs; inspect `jobs list` and wait for those before exporting. Jobs continue on the server if the CLI exits. `files export` refuses to overwrite a file. `projects rename PROJECT_ID --name "New name"` and `projects delete PROJECT_ID --yes` manage the library. `projects move PROJECT_ID --to OTHER_PROJECT_ID --characters SLUG,SLUG --assets ASSET_ID --avatars GROUP_ID` moves characters (with all their animations), saved assets and the project's own avatars to another project you can write to, without regenerating anything (CLI 0.16.0). `models PROJECT_ID --video-model heygen/heygen-video-1` sets the defaults for future jobs. Image generation follows staff-managed main and backup routes and has no user model selector.
 
 Generation and reference imports require `--yes`, which authorizes credit spending. Read estimates from `projects get` before submitting. Estimates are ranges; actual provider usage is recorded to your own balance. Paid generation needs configured production provider bindings and secrets.
 
@@ -124,21 +124,21 @@ List valid identifiers with `animaguru catalog`. Set models on a single generati
 
 ```sh
 animaguru generate PROJECT_ID --name "Knight" --description "A blue knight" \
-  --image-model gpt-image-2.5 --video-model heygen/heygen-video-1 \
+  --video-model heygen/heygen-video-1 \
   --actions idle,walk --yes
 ```
 
-`generate`, `jobs submit`, and `files import` accept both `--image-model` and `--video-model`. The video selection is used when the job includes an animation. These overrides apply to that job and the animations it explicitly queues; they do not change project defaults. `jobs submit` flags take precedence over `imageModel` and `videoModel` fields in its JSON file. Model identifiers are validated before a job is queued. Jobs return and retain the selected model identifiers, even if project defaults change while they wait.
+`generate`, `jobs submit`, and `files import` accept both `--video-model`. The video selection is used when the job includes an animation. Image models are selected centrally by staff, with automatic backup routing; users and agents cannot override them. Video overrides apply to that job and the animations it explicitly queues; they do not change project defaults. `jobs submit` flags take precedence over `videoModel` fields in its JSON file. Model identifiers are validated before a job is queued. Jobs return and retain the selected model identifiers, even if project defaults change while they wait.
 
 Set defaults for all future jobs in a project:
 
 ```sh
-animaguru models PROJECT_ID --image-model gpt-image-2.5 --video-model pruna/p-video-2-pro
+animaguru models PROJECT_ID --video-model pruna/p-video-2-pro
 # Either selection can be changed independently:
 animaguru models PROJECT_ID --video-model heygen/heygen-video-1
 # Or choose them when creating a project:
 animaguru projects create --name "Forest cast" \
-  --image-model gpt-image-2.5 --video-model heygen/heygen-video-1
+  --video-model heygen/heygen-video-1
 ```
 
 An omitted model uses the saved project selection, then the service default. Credit estimates and supported quality settings follow the selected video provider. Reference or redraw operations use the existing GPT Image fallback when the selected image model does not support edits. Configured provider secrets are required for actual generation.
@@ -154,8 +154,17 @@ animaguru projects create --name "Adventure assets"
 animaguru assets list PROJECT_ID
 
 animaguru assets generate PROJECT_ID --type image --name "Forest" \
-  --prompt "A moonlit watercolor forest" --model gpt-image-2.5 \
-  --aspect-ratio 3:2 --yes
+  --prompt "A moonlit watercolor forest" --aspect-ratio 3:2 --yes
+
+# Keep a character the same from scene to scene by following a saved character sheet.
+animaguru assets generate PROJECT_ID --type image --name "Marie in the lab" \
+  --prompt "Marie from Image 1, same face, hair and coat, measuring a glowing vial at her bench" \
+  --references CHARACTER_SHEET_SHA --aspect-ratio 16:9 --yes
+
+# Change only the right half of a saved scene; the rest stays as it is.
+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 \
@@ -212,16 +221,50 @@ animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
 
 `--end-reference` can be used without `--reference`; the video then ends on that image. `--soundtrack` takes a music, speech or SFX asset's `file` SHA and replaces the generated sound; the video must be at least 2 seconds. Text-to-video takes `--aspect-ratio` 21:9, 16:9 (default), 4:3, 1:1, 3:4 or 9:16. Extensions take a video asset's SHA as `--source` (1.6–60 seconds, up to 50 MB), bill `--seconds` of new footage, offer 2K, and keep the source's shape unless `--aspect-ratio` crops it. `--extend-output continuation` returns only a 1.625-second overlap and the new footage. Extensions take up to three comma-separated `--audio-references` (2–15 seconds each, 15 seconds in total); refer to them in the prompt as Audio 1, Audio 2 and so on. `--prompt-expansion` is `disabled` (default), `balanced` or `quality`; for extensions, any value other than `disabled` turns expansion on. Each model's `videoProfiles` entry in `catalog` lists its workflows, resolutions and options. The server needs `AI_PROVIDER_KEY_FAL`.
 
-Images have a full background by default; `--transparent` requests a cutout. Gemini speech's `--prompt` is the verbatim transcript, and `--delivery` controls how it sounds without being spoken. Gemini speech supports both `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts`. Music uses Lyria. Google audio requires the server's `AI_PROVIDER_KEY_GOOGLE` secret; no provider keys are stored in the CLI.
+CLI 0.18.0 adds MiniMax H3 Max's eight other workflows (`fal/minimax-h3-max`, not Turbo):
+
+```sh
+# Keep Marie the same across scenes: reference images, a clip and audio, named in the prompt.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow reference-to-video --name "Marie at the market" \
+  --prompt "Image 1 is Marie. She walks through the market in Video 1's style, humming Audio 1" \
+  --references CHARACTER_SHEET_SHA,MARKET_SHA --reference-videos CLIP_SHA --audio-references SONG_SHA \
+  --seconds 6.5 --resolution 768p --dry-run
+# Make the face in an image say saved speech; the video lasts as long as the speech.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow lip-sync --name "Marie explains" --reference PORTRAIT_SHA --soundtrack SPEECH_SHA \
+  --transcribe --resolution 768p --dry-run
+# Orbit the camera half way around a still scene.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow camera-controls --name "Product reveal" --reference PRODUCT_SHA \
+  --camera "0,0,10,1;1,180,10,1.2" --seconds 6 --dry-run
+# Film in a preset look.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow style --style vhs --damage light --name "Home video" \
+  --prompt "A birthday party in a backyard, 1989" --aspect-ratio 4:3 --dry-run
+```
+
+- `reference-to-video` keeps the subjects or look of up to nine `--references` images, three `--reference-videos` (2–15 seconds each, 15 in total) and three `--audio-references`, twelve files in all. Name them in the prompt as Image 1, Video 1, Audio 1 and so on. It can also open on `--reference`, end on `--end-reference`, and pass `--middle-reference` at `--middle-seconds`; a middle image needs both of the others and 480p or 768p. `--aspect-ratio auto` (default) follows the inputs.
+- `lip-sync` makes the face in `--reference` (an image between 2:5 and 5:2) say `--soundtrack`, speech of 5 seconds to 15 minutes. It takes no prompt and goes up to 2K. `--transcribe` transcribes the speech to guide the mouth. Past 15 seconds it costs 1.2× per second.
+- `camera-controls` moves the camera around `--reference` along `--camera` keyframes `time,azimuth,elevation,distance`. `time` runs from 0 at the start to 1 at the end, and the angles are in degrees (elevation −90 to 90). Use 2–12 keyframes, separated by semicolons. Without a prompt the scene stays still and only the camera moves.
+- `insert-video` adds a new scene of `--seconds` (5–13) to `--source`, starting `--insert-at` seconds in and handing back to the source at `--resume-at`. The prompt, `--references` and `--reference-videos` guide the scene. It renders at 480p or 768p, and `--no-color-match` turns off matching the source's colors.
+- `recast` puts the people in `--references` (one photo each, up to four, left to right) in place of the people in `--source` (5–30 seconds), at 768p or 1080p. Pass `--subject-consent` only after each person in the photos agreed to appear. `--enhance-realism` blends them in more naturally.
+- `relight` relights `--source` (up to 15 seconds) from `--lighting`, an image of a sphere lit the way you want. It takes no prompt, keeps the source's shape unless `--aspect-ratio` crops it, and goes up to 2K.
+- `3d-to-video` turns `--source`, a 3D render up to 15 seconds long, into realistic footage. It follows up to eight `--references`, or draws its own (`--generated-references`, 1–8, default 2). It takes no seed and costs at least 5 seconds.
+- `style` films in a preset look: `vhs` (with `--damage light|medium|heavy`), `retro-toon-70s`, `low-poly`, `hand-drawn` or `16bit-pixel`. It renders at 768p for 5–15 whole seconds, from the prompt with `--aspect-ratio`, or from `--reference` as the first frame.
+
+H3 takes fractions of a second (`--seconds 6.5`). Lip-sync, recast, relight and 3d-to-video last as long as their speech or video, and `--seconds` doesn't apply to them. Reference images, clips and audio past fal's included allowance add to the cost; so do the references 3d-to-video draws. Their `--dry-run` asks the server, which measures the saved files. `--resolution` and `--mode` default to the first the workflow offers.
 
-Preview a validated request and its estimated credits offline with `--dry-run`, without signing in or spending credits:
+Images have a full background by default; `--transparent` requests a cutout. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 shapes. `--aspect-ratio` is 1:1 (default, 1024×1024), 3:2 (1536×1024), 2:3 (1024×1536), 16:9 (1536×864) or 9:16 (864×1536). `--references` takes up to four comma-separated blob SHAs of this project's images (including attached uploads) or sprite art, and the new image follows them: generate a character sheet once, then reference it in every scene to keep the character consistent. Refer to them in the prompt as Image 1, Image 2 and so on, and say what to take from each. Each reference adds a little to the estimate. `--mask` edits only part of Image 1, the first reference: give up to eight rectangles as `x,y,width,height` fractions of its size from the top left, separated by semicolons (`0,0,1,0.4` is the top 40%). The rest of the image is kept, and the result keeps Image 1's shape, which must be one of the five above. Gemini speech's `--prompt` is the verbatim transcript, and `--delivery` controls how it sounds without being spoken. Gemini speech supports both `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts`. Music uses Lyria. Google audio requires the server's `AI_PROVIDER_KEY_GOOGLE` secret; no provider keys are stored in the CLI.
+
+Preview a validated request and its estimated credits with `--dry-run`, without spending credits; most dry runs work offline without signing in:
 
 ```sh
 animaguru assets generate PROJECT_ID --type music --name "Theme" \
   --prompt "A gentle instrumental theme" --dry-run
 ```
 
-Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. Omit `--dry-run` and pass `--yes` to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:
+Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. The exceptions are H3 Max's lip-sync, recast, relight, 3d-to-video, reference-to-video and insert-video: their prices depend on the saved files' lengths and shapes, so their dry runs are signed-in server estimates. Omit `--dry-run` and pass `--yes` to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:
 
 ```json
 {"type":"speech","name":"Welcome","prompt":"Welcome, traveler.","model":"gemini-3.8-flash-lite-tts","voice":"Kore","delivery":"Warm and welcoming"}
@@ -351,6 +394,30 @@ animaguru motion get skeleton-list-swipe --write animations/launch/src/scenes
 
 Then call the entry function from `Film.build()`, for example `skeletonListSwipe(this, { at: 4 })`. `--write` refuses to replace an existing scene (pass `--force`) and keeps shared modules that already exist.
 
+## Brand kits
+
+Use saved personal or team brands across films. `brands list`, `create` and `research` use the selected cloud workspace; `--workspace personal` or `--workspace TEAM_ID` overrides it for that command. Commands taking a brand ID check access to that brand's workspace.
+
+```sh
+animaguru brands list
+animaguru brands get BRAND_ID
+animaguru brands create --name "Penny" --website https://penny.example.com
+animaguru brands create --file brand-fields.json
+animaguru brands research https://penny.example.com --name "Penny"
+animaguru brands upload BRAND_ID --file logo.svg --kind logo --yes
+animaguru brands update BRAND_ID --file brand-patch.json
+animaguru brands download BRAND_ID --output ./my-film-workspace
+animaguru brands download BRAND_ID --file BRAND_FILE_ID --output ./my-film-workspace
+```
+
+Manual creation accepts a JSON object with `name`, `website`, `tagline`, `colors`, `fonts` and Markdown `guide`; `--name`, `--website` and `--tagline` override it. Omitted colors and fonts use neutral defaults. Colors use six-digit hex values: `primary`, `background`, `text`, optional `accent` and named `palette` entries. Fonts have `heading` and `body` objects with a CSS `family`. New kits start without file references. `research` instead researches the supplied official HTTPS website asynchronously; inspect `brands get BRAND_ID` until `status` is `ready` or `failed`. Keep the returned brand ID when polling. Both creation commands accept `--request-id UUID` to retry the same creation without duplicating it.
+
+Uploads support SVG, PNG, JPEG, WebP, GIF, web fonts, audio and video up to 32 MiB per file. The media type is inferred from the extension or supplied with `--mime-type`. An upload returns the saved file ID; `--kind logo` labels its role. To make it the primary logo, update with a JSON patch such as `{"logo":"bf_…"}`; additional media use `{"assets":["bf_…"]}`. File references must belong to that brand. Updates wait until research finishes.
+
+Downloads save a shared `branding/` directory under `--output`, including `brand.json`, `brand-guide.md` and all media with paths ready for the film exporter. `--file BRAND_FILE_ID` saves only that media file. Existing files require `--force`; symbolic links are refused. Refresh the download after changing the saved kit. Listing, reading, manual creation, uploads, updates and downloads spend no generation credits.
+
+MCP provides `list_brands`, `get_brand`, `create_brand`, `research_brand`, `update_brand`, `upload_brand_image` and `download_brand`. Read tools require `projects.read`; creation, research, updates and uploads require `projects.write` and workspace write access. `upload_brand_image` takes `brand_id` and `image: {name, kind, url}` for a public HTTPS image up to 32 MiB, or `{name, kind, data, mimeType}` for standard base64 up to 8 MiB. `download_brand` returns text files and 15-minute signed file links that recheck workspace access. Pass `file_id` to get only one file's link.
+
 ## Asset library
 
 CLI 0.15.0 adds `animaguru library`. Pro and Team accounts (and members of a team on the Team plan) can search AnimaGuru's asset library: ready-made sprites with animation sheets, images, video clips, music, voice-over speech and sound effects. Search uses natural language and keywords together. Importing into a project or downloading spends no credits, so check the library before generating a common asset.
@@ -442,12 +509,13 @@ Only one YouTube command may run at a time. Normal cancellation releases its loc
 
 ## Cloud sync and versions
 
-CLI 0.11.0 adds `animaguru cloud` for Individual Pro and Team plans. It saves a video workspace, or a standalone video project, to AnimaGuru with every version. Use it to continue on another computer, work with your team and return to earlier versions. Personal cloud projects need your own Individual Pro or Team plan. A team's cloud projects need the team owner's Team plan, and every member can then save and download them.
+CLI 0.11.0 adds `animaguru cloud` for Individual Pro and Team plans. It syncs a video workspace, or a standalone video project, with an AnimaGuru project's animations and keeps every version. Use it to continue on another computer, work with your team and return to earlier versions. The studio shows the synced films on the project's **Animations** tab, next to its assets and Animator drafts. Syncing a personal project needs your own Individual Pro or Team plan. A team's projects need the team owner's Team plan, and every member can then save and download their animations.
 
 ```sh
 animaguru auth login
-animaguru workspaces use TEAM_ID              # optional: create the cloud project in a team
-animaguru cloud link                         # creates a cloud project for this folder
+animaguru workspaces use TEAM_ID              # optional: create the project in a team
+animaguru cloud link                         # creates a project named after this folder and syncs with it
+animaguru cloud link --project PROJECT_ID    # or: sync with an existing project (prj_…)
 animaguru cloud push -m "First cut"          # saves a version
 animaguru cloud status                       # unsaved changes, and whether the cloud is newer
 animaguru cloud pull                         # brings in versions saved elsewhere
@@ -455,7 +523,7 @@ animaguru cloud versions                     # newest first, with who saved each
 animaguru cloud restore VERSION --path animations/intro/src
 animaguru cloud push                         # saves the restored files as the newest version
 animaguru cloud clone PROJECT_ID my-films    # another computer; run npm install afterwards
-animaguru cloud list
+animaguru cloud list                         # projects with synced animations
 ```
 
 Run the commands anywhere inside the workspace; `--dir PATH` chooses another folder. What is not synced:
@@ -465,7 +533,7 @@ Run the commands anywhere inside the workspace; `--dir PATH` chooses another fol
 - anything matched by `.gitignore` or `.animaguruignore`;
 - symbolic links.
 
-Each version is a Git commit in the project's own Cloudflare Artifacts repository. Where a file is stored depends on its type, not its size:
+Each version is a Git commit in the project's own animations repository on Cloudflare Artifacts. Where a file is stored depends on its type, not its size:
 
 - **Media** (images except SVG, video, audio and ZIP bundles) is uploaded once by SHA-256 at any size, however many versions use it, and Git keeps a small pointer. Media counts toward the plan's media storage: 20 GB for Individual Pro and 100 GB for each team.
 - **Work files** (code, configs, briefs, JSON, SVG, fonts and everything else) are stored in Git at any size up to Artifacts' 32 MB per-file limit. A larger work file stops the push and is named; add it to `.animaguruignore` or move it.
@@ -479,7 +547,7 @@ The sync store lives in `.animaguru/sync/`, separate from any Git repository you
 
 `restore` makes the folder, or the `--path` files and folders, match an earlier version without rewriting history. Push afterwards to save the result as the newest version. Replacing unsaved changes requires `--yes` and keeps backups.
 
-Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a plan ends, cloud projects stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. `cloud unlink` stops syncing a folder without touching the cloud. `cloud delete PROJECT_ID --yes` deletes the project, all its versions and its stored files. The studio's Cloud page lists projects, versions and their files, with downloads.
+Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a plan ends, synced animations stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. `cloud unlink` stops syncing a folder without touching the cloud. `cloud delete PROJECT_ID --yes` deletes the project's animations with all their versions, Animator drafts and stored files; the project and its assets stay. A project's **Animations** tab in the studio lists its films, versions and their files, with downloads.
 
 ## One brand, many animations