@docyrus/animaguru 0.16.1 → 0.17.0

package/NOTICE.md

@@ -1526,3 +1526,30 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+
+## Art Motion references
+
+English adaptations of Huashu Art Motion (https://github.com/alchaincyf/huashu-art-motion). Source revision and coverage are in skills/animaguru-art-motion/references/coverage.json.
+
+MIT License
+
+Copyright (c) 2026 alchaincyf (花叔 · 花生)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -31,8 +31,18 @@ From this repository, `npm ci && npm run cli:build` builds the CLI and `npm run
 
 The command `animaguru schema` returns the Crust command schema, and `animaguru catalog` lists supported art styles, actions, asset types, models, video profiles and speech voices; `catalog --type music` (or `sprites`, `image`, `video`, `speech`, `sfx`, `avatars`) returns only that part. Shell completions: `animaguru completion zsh` (also bash and fish).
 
+## Required updates
+
+Starting with CLI 0.16.2, commands check `https://animaguru.com/cli/release.json` before doing work. When a newer stable release is available, the command exits nonzero before running and prints a JSON `cli_update_required` error to stderr, including the installed/latest versions and update instructions. This applies to humans and agents, including local scaffolding and dry runs. Run the same macOS installer again, or use the npm command in the error for an npm installation, verify `animaguru --version`, and retry the original command.
+
+`animaguru update` checks the current release and prints JSON with update instructions; it does not install anything. Help, `--version`, `schema`, shell completion, and `auth logout` remain available while outdated. The check has a three-second timeout and sends no account credentials. If it fails, the last known release in `~/.config/animaguru/cli-release.json` (or `ANIMAGURU_CONFIG_DIR`) still enforces a known update. With no known newer version, offline work continues with a warning. A successful check on the next invocation refreshes the saved release.
+
+CLI versions before 0.16.2 need one manual update to gain enforcement. Publish the npm release before deploying the matching site release so the required version is available through both installation methods.
+
 ## Create an animation video project
 
+CLI 0.16.2 also installs `animaguru-art-motion` for Codex and Claude Code: one skill with 36 English art-treatment references and nine explainer motion grammars, plus AnimaGuru generation, timing, camera and review guidance. Request it explicitly for a custom film treatment; its references are separate from the gallery presets. Source coverage and the upstream MIT notice are included in the skill.
+
 CLI 0.5.2 includes a complete local PixiJS video workspace with 31 visual styles:
 
 ```sh
@@ -104,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.
 
@@ -114,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.
@@ -144,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 \
@@ -202,7 +221,7 @@ 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.
+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 offline with `--dry-run`, without signing in or spending credits:
 
@@ -341,6 +360,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.
@@ -432,12 +475,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
@@ -445,7 +489,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:
@@ -455,7 +499,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.
@@ -469,7 +513,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