@docyrus/animaguru 0.6.0

package/NOTICE.md

@@ -0,0 +1,256 @@
+# Third-party notices
+
+AnimaGuru bundles the following libraries. Their licenses apply to their respective components.
+
+## @crustjs/core 0.5.4
+
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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.
+
+## @crustjs/extensions 0.5.4
+
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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.
+
+## @crustjs/store 0.4.4
+
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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.
+
+## @crustjs/style 0.3.6
+
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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.
+
+## @crustjs/utils 0.2.2
+
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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.
+
+## fflate 0.8.3
+
+MIT License
+
+Copyright (c) 2026 Arjun Barrett
+
+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.
+
+## zod 4.6.5
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+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.
+
+## Official PixiJS skills
+
+Bundled from https://github.com/pixijs/pixijs-skills. Snapshot hashes are in vendor/pixijs-skills/provenance.json.
+
+MIT License
+
+Copyright (c) 2026 PixiJS
+
+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.
+
+
+## Video style references
+
+Video style sources and notices
+
+The executable studies and preview art are original AnimaGuru procedural 2D/2.5D work. Material/motion guidance was adapted from the pinned repositories below. No external creator video, sample music or demo font is bundled. Third-party demo assets retain their own licenses.
+
+lemo-opuscar
+MIT License
+
+Copyright (c) 2026 LemoLab
+
+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.
+
+Third-party assets in the demos (sample libraries, fonts, music, voices) keep their own
+licences; see each demo's CREDITS. You are responsible for the materials you use in your
+own films.
+
+
+awesome-opus5-5-videos
+MIT License
+
+Copyright (c) 2026 yihui-dev
+
+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

@@ -0,0 +1,241 @@
+# AnimaGuru CLI
+
+CrustJS CLI for humans and agents. Requires Node.js 24 or later. Success output is JSON on stdout; login instructions and errors go to stderr. Errors exit nonzero. Tokens are never printed by the CLI.
+
+## Install on macOS
+
+Paste this command into Terminal. It supports Apple Silicon and Intel Macs and needs no sudo or Homebrew:
+
+```sh
+curl -fsSL https://animaguru.com/install.sh | bash
+```
+
+Or download [the Mac installer](https://animaguru.com/cli/AnimaGuru-Installer-Mac.zip), unzip it, and double-click **Install AnimaGuru.command**. It opens Terminal and runs the same installer.
+
+The installer verifies the package checksum, uses an installed Node.js 24+ when available, or downloads a private Node.js 24 runtime from nodejs.org and verifies its checksum. It installs into `~/.local/share/animaguru`, places a launcher in `~/.local/bin`, and adds that directory to your zsh or bash startup file. Open a new terminal afterward or use the full launcher path printed by the installer. Run the installer again to upgrade. It does not change your system Node.js installation or your AnimaGuru sign-in credentials.
+
+For custom locations set `ANIMAGURU_INSTALL_DIR` and `ANIMAGURU_BIN_DIR` to absolute paths. `ANIMAGURU_SKIP_PATH=1` disables shell-profile editing. Remove the launcher and installation directory to uninstall; credentials are stored separately.
+
+## Install from npm
+
+```sh
+npm install -g @docyrus/animaguru
+animaguru auth login
+animaguru auth status
+animaguru credits
+```
+
+The npm package requires Node.js 24+. Its default registry is https://registry.npmjs.org/. The package has no runtime npm dependencies; third-party notices are included.
+
+From this repository, `npm ci && npm run cli:build` builds the CLI and `npm run cli -- --help` runs it. `npm run cli:release` prepares the npm tarball and public Mac downloads. `npm run cli:publish` publishes that reviewed release under the Docyrus organization; publishing requires a logged-in npm account with organization access and any required 2FA. Each release needs a new version in `cli/package.json`; the CLI version is read from that file. `npm run deploy` builds release downloads before uploading the site.
+
+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. Shell completions: `animaguru completion zsh` (also bash and fish).
+
+## Create an animation video project
+
+CLI 0.5.2 includes a complete local PixiJS video workspace with 31 visual styles:
+
+```sh
+animaguru templates
+animaguru create my-video
+```
+
+`create` takes only the project folder name. Use a new folder whose parent already exists; the command refuses existing destinations, including empty folders and symlinks. It installs PixiJS, Vite, TypeScript and FFmpeg/FFprobe tools. npm progress goes to stderr and successful results are JSON. If installation fails, the generated files remain; enter the folder and run `npm install` to resume.
+
+Open the generated folder in **Codex or Claude Code**, then describe the video you want. It includes:
+
+- An AnimaGuru-branded player with a playable animated demo, resource timeline, captions, seeking, fullscreen, frame downloads and transcript. The timeline shows resource clips, follows playback, and supports selection, zoom and frame-accurate scrubbing.
+- Local AnimaGuru and official PixiJS skills in both `.agents/skills/` and `.claude/skills/`, plus `AGENTS.md` and `CLAUDE.md`.
+- Agent instructions that first ask **Explainer, Advertisement or General Video**, then offer the available visual styles and [the preview gallery](https://animaguru.com/animation-styles), then gather a short creative brief. Each choice is saved before continuing.
+- `film.config.json`, editable TypeScript scenes, localized copy, local asset/production folders, portable HTML5 ZIP export for iframe embedding, and `npm run export:mp4` with exact frame capture and output verification.
+
+New projects leave category and template unset in `animaguru.project.json`. `animaguru.templates.json` lists categories, styles and their installed skills. The 31 visual styles cover cutout, type, vector, technical, character, print, paper, material and cinematic treatments. Every style skill ships with the project, including its relevant visual interview and review criteria. Categories describe purpose and templates describe appearance and motion. The brief establishes audience, tone, message, story, duration and any CTA.
+
+Scaffolding requires no AnimaGuru sign-in and spends no generation credits; dependency installation requires npm access. `npm run dev` previews the project, and `npm run build` checks and bundles it. To export, run `npm run export:mp4`, open its local URL and wait for the verified MP4, or use HTML5 export for embedding. The starter demo is silent; the agent creates narration and music when in scope.
+
+The official PixiJS skills are vendored with their MIT license and a hashed provenance manifest. Skills and template files ship in both the npm package and macOS installer; `create` does not fetch agent instructions from a remote repository at runtime.
+
+## Install the project skill
+
+Run this in the folder where you want your coding agent to use AnimaGuru:
+
+```sh
+cd /path/to/your/project
+animaguru init
+```
+
+Available in CLI 0.3.0 and later, `init` writes the bundled skill to `.agents/skills/animaguru/SKILL.md` in the current folder. It works offline without signing in and returns JSON containing the absolute `path` and a `created` boolean. The skill explains project selection, credit authorization, generation, animation, reference imports, waiting for jobs, and exporting assets.
+
+Running `init` again refreshes an existing skill with the bundled version without a warning or confirmation (`created: false`). An identical skill is left unchanged. Skill installation happens when you explicitly run `init` or scaffold a new project with `create`. The npm and macOS packages both include the skill.
+
+## Authentication and server
+
+The default server is https://animaguru.com. Use `--url http://localhost:5190` on the leaf command or `ANIMAGURU_URL` to override it. HTTP is allowed only for loopback development. Authentication is stored separately per server in `~/.config/animaguru/credentials.json`, with file permissions 0600. Set `ANIMAGURU_CONFIG_DIR` for an isolated configuration directory. Browser login uses a ten-minute, single-use device code and receives a seven-day revocable Better Auth session. `auth login --no-browser` prints the URL for manual use. `auth logout` revokes the token. `ANIMAGURU_TOKEN` supports secret injection by agent runners; do not put tokens in arguments or commit them.
+
+## Agent workflow
+
+```sh
+animaguru projects create --name "Forest cast" --style pixel
+# Read the returned project.id and use it below.
+animaguru generate PROJECT_ID --name "Knight" --description "A blue knight with a red scarf" --actions idle,walk --yes
+animaguru jobs wait PROJECT_ID JOB_ID --timeout 600
+animaguru jobs list PROJECT_ID
+animaguru projects get PROJECT_ID
+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. `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`.
+
+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.
+
+## Image and video model parameters
+
+List valid identifiers with `animaguru catalog`. Set models on a single generation:
+
+```sh
+animaguru generate PROJECT_ID --name "Knight" --description "A blue knight" \
+  --image-model gpt-image-2.5 --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.
+
+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
+# 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" --style pixel \
+  --image-model gpt-image-2.5 --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.
+
+These flags are available in CLI 0.2.0 and later. Rerun the macOS installer to upgrade.
+
+## Image, video, music and speech generation
+
+CLI 0.4.0 adds standalone assets alongside the existing sprite commands. Use any project, or create an empty one first. `assets list` returns saved asset ids, image blob hashes for video references, and the models configured on that server.
+
+```sh
+animaguru projects create --name "Adventure assets" --style hd-cartoon
+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
+
+animaguru assets generate PROJECT_ID --type video --name "Forest breeze" \
+  --prompt "Leaves drift slowly in the breeze" --reference IMAGE_BLOB_SHA \
+  --model pruna/p-video-2-pro --seconds 5 --resolution 768p --mode quality --yes
+
+animaguru assets generate PROJECT_ID --type music --name "Adventure theme" \
+  --prompt "An instrumental adventure theme with flute and strings" --model lyria-3.5 --yes
+
+animaguru assets generate PROJECT_ID --type speech --name "Welcome" \
+  --prompt "Welcome, traveler. Your next adventure starts here." \
+  --model gemini-3.8-flash-lite-tts --voice Kore --delivery "Warm and welcoming" --yes
+
+animaguru jobs wait PROJECT_ID JOB_ID --timeout 900
+animaguru assets list PROJECT_ID
+animaguru assets download PROJECT_ID ASSET_ID --output welcome.wav
+animaguru files export PROJECT_ID --output adventure-assets.zip
+```
+
+Use the returned job id with `jobs wait`. For `--reference`, use an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, from the same project. Video duration, resolution and mode must match its provider's profile in `catalog`; omitted video options use five seconds and that model's first supported resolution and mode. Standalone assets use their type's default model when `--model` is omitted; sprite project model defaults continue to apply to sprite commands.
+
+CLI 0.5.0 adds ElevenLabs speech and SFX:
+
+```sh
+animaguru assets generate PROJECT_ID --type speech --model eleven_v4 \
+  --name "Narration" --prompt "[whispers] Welcome, traveler." \
+  --voice JBFqnCBsd6RMkjVDRZzb --dry-run
+animaguru assets generate PROJECT_ID --type speech --model eleven_v4_turbo \
+  --name "Greeting" --prompt "Hello, traveler." --dry-run
+animaguru assets generate PROJECT_ID --type sfx --name "Magic spell" \
+  --prompt "A shimmering spell with a soft burst" --seconds 2.5 --loop \
+  --prompt-influence 0.6 --dry-run
+```
+
+Replace `--dry-run` with `--yes` to generate within your authorized credit budget. ElevenLabs accepts a voice ID in `--voice` and defaults to George when omitted. Use audio tags in the transcript; `--delivery` is only for Gemini and is rejected for ElevenLabs. SFX has a single model, `eleven_text_to_sound_v2`; `--seconds` accepts 0.5–30 (default 5), `--loop` requests a seamless loop, and `--prompt-influence` accepts 0–1 (default 0.3). Both return MP3. `catalog` includes `sfxModels` and `elevenLabsVoices`. The server needs `AI_PROVIDER_KEY_ELEVENLABS`; provider keys never belong in CLI credentials.
+
+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.
+
+Preview a validated request and its estimated credits offline with `--dry-run`, without signing in or spending credits:
+
+```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:
+
+```json
+{"type":"speech","name":"Welcome","prompt":"Welcome, traveler.","model":"gemini-3.8-flash-lite-tts","voice":"Kore","delivery":"Warm and welcoming"}
+```
+
+```sh
+animaguru assets submit PROJECT_ID --file speech.json --dry-run
+animaguru assets submit PROJECT_ID --file speech.json --model gemini-3.8-flash-tts --yes
+```
+
+`--model` overrides the file's model. Unrelated type-specific flags are rejected rather than ignored. Individual downloads and complete ZIP exports refuse to overwrite existing files. Generated files are saved in the project's `assets/<id>/` directory and are shared with the web Assets workspace.
+
+## Typed job files
+
+Use `animaguru jobs submit PROJECT_ID --file job.json --yes`. The server and CLI validate the same schema. Available job bodies:
+
+```json
+{"kind":"character","name":"Knight","description":"A blue knight with a red scarf","style":"pixel","subjectKind":"character","actions":["idle","walk"]}
+```
+
+```json
+{"kind":"animate","character":"knight-SLUG","actions":["run","jump"]}
+```
+
+```json
+{"kind":"redraw","character":"knight-SLUG","change":"Give the knight a green helmet"}
+```
+
+For named motions, especially video and collage subjects:
+
+```json
+{"kind":"custom","character":"knight-SLUG","name":"Wave hello","prompt":"The character raises one arm, waves twice and lowers it back to its starting pose, staying in place.","frames":["Arm resting by the side","Arm raised with open hand","Hand waving to the right","Arm resting by the side"],"loop":false,"returns":true,"fps":12}
+```
+
+Custom motions require 2–12 frame descriptions, a 20–600 character prompt, and 4–24 fps. Character identifiers are returned by `projects get`. Built-in actions must match the subject kind.
+
+Reference images:
+
+```sh
+animaguru files import PROJECT_ID --file knight.png --name Knight --description "Keep the blue armor" --yes
+```
+
+PNG, JPEG and WebP are accepted up to 10 MB. A configured service redraws the reference and charges credits; otherwise it imports the original artwork.
+
+## Expanded video workflows and studies
+
+New workspaces offer Explainer, Advertisement and General Video independently of visual style. Eight advertising and five general-video workflows are installed as focused references. Existing `advertorial` project choices remain compatible; completed briefs and style IDs are reused.
+
+Twenty original procedural 2.5D studies are bundled. In an untouched project, `npm run example -- risograph-print` installs a runnable study, with starter backups and refusal to replace an authored film. `npm run review` prints a local browser URL and saves text-bound checks, deterministic seek comparisons and frames to `production/review/`. Review moving playback and audio too. Physically rendered 3D is deferred.
+
+## Submit and share videos
+
+Run `animaguru auth login`, then submit from a finished AnimaGuru video workspace:
+
+```sh
+animaguru submit --yes                            # Builds and hosts HTML5; private
+animaguru submit --share "alex@example.com" --yes  # Private review for a verified account
+animaguru submit --visibility public --yes         # Listed at https://animaguru.com/videos
+animaguru submit --file production/exports/film.mp4 --poster public/assets/cover.png --yes
+animaguru submit --file production/exports/film.zip --dry-run
+```
+
+An optional positional directory selects the workspace; file and poster paths are relative to it. HTML5 exports upload the compiled animation and local media; source code, project instructions, credentials and generation receipts are not submitted. MP4 and AnimaGuru HTML5 ZIP are both supported. The CLI prints the video ID and full watch URL. Public HTML5 videos offer embed markup on the watch page; private sharing requires the selected AnimaGuru users to sign in.
+
+`videos list --scope mine|shared|public` lists films. Owners can edit metadata, change visibility and replace recipients on the website, or use `videos share VIDEO_ID --visibility private --share "alex@example.com" --yes`. `videos delete VIDEO_ID --yes` removes the film and files. Making a film private or removing a recipient revokes access to existing playback links.
+
+Uploads are divided into SHA-256 verified 8 MiB parts. Interrupted submissions print their video ID: inspect with `videos get VIDEO_ID`, retry a fully uploaded film with `videos complete VIDEO_ID`, or delete the unfinished draft before resubmitting. Completion is idempotent. HTML5 ZIPs allow 64 MiB compressed / 96 MiB expanded with 500 entries and 32 MiB per asset; MP4s allow 512 MiB; PNG/JPEG/WebP covers allow 2 MiB. Uploads are available to verified accounts with a 2 GiB video library allowance. Hosting does not run paid generation jobs.