@shotstack/cli 0.7.1 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Command-line interface for the Shotstack video rendering API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/shotstack/shotstack-cli",
@@ -27,7 +27,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@shotstack/schemas": "^1.12.2",
+    "@shotstack/schemas": "^1.17.0",
     "commander": "^12.1.0",
     "zod": "^4.4.3"
   },

package/skills/shotstack/SKILL.md

@@ -13,7 +13,9 @@ license: Apache-2.0
 
 This skill loads in **terminal-based AI agents** (Claude Code, Cursor, Codex CLI, Gemini CLI, etc.). All operations here are shell commands. There is no embedded UI, no iframe, no inline canvas, no MCP tool surface — only `shotstack` invocations from a terminal. To hand off to a human, run `shotstack studio <file>`; this opens the user's default browser to a `shotstack.studio` URL. Tell the user to click Render *in the browser tab*, not in any UI inside the terminal.
 
-Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render.
+**Open-ended first render? Ask before composing.** If the ask doesn't state what the video is (subject, format or destination) — e.g. "render my first video", "make me a video", "set up Shotstack" — read [`references/onboarding.md`](references/onboarding.md) and ask its discovery questions, then WAIT for answers. Do not write an Edit first. An open-ended ask is not a specification, and a stray JSON file in the project doesn't make the user experienced. Compose without asking only when the user has stated what the video is, or explicitly says to just show anything.
+
+Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one.
 
 **Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
 
@@ -151,6 +153,7 @@ Authoritative sources, in order of preference:
 
 This skill ships sub-references for the gnarly bits:
 
+- [`references/onboarding.md`](references/onboarding.md) — first-render discovery interview for new users: what to ask, and how answers map to a first Edit
 - [`references/ingest.md`](references/ingest.md) — uploading local files (and fetching URLs) so they can be used in an Edit: the upload→render workflow, `--watch`, status values, supported types
 - [`references/timeline.md`](references/timeline.md) — track layering, transitions, background music via audio assets
 - [`references/positioning.md`](references/positioning.md) — coordinate model, `position`/`offset` (fraction of frame, +y up), clip bounding box & `fit`, text sizing, transform order

package/skills/shotstack/references/fonts.md

@@ -34,26 +34,9 @@ Load a font from a public URL via `timeline.fonts[]`, then reference its **file
 
 The `font.family` value is the URL's filename without extension, and it **must** match the URL's basename exactly. For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`. If `family` and the URL basename diverge, the font silently fails to load.
 
-## Verified font catalogue (12 fonts)
+## Verified font catalogue
 
-Copied verbatim from the Studio SDK catalogue. Paste the **url** into `timeline.fonts[].src`, paste the **family** into `asset.font.family`.
-
-| Font (style) | family (use in `font.family`) | url (use in `timeline.fonts[].src`) |
-|---|---|---|
-| Inter (sans, variable) | `UcCo3FwrK3iLTfvlaQc78lA2` | `https://fonts.gstatic.com/s/inter/v20/UcCo3FwrK3iLTfvlaQc78lA2.ttf` |
-| Roboto (sans, variable) | `KFOmCnqEu92Fr1Me5WZLCzYlKw` | `https://fonts.gstatic.com/s/roboto/v50/KFOmCnqEu92Fr1Me5WZLCzYlKw.ttf` |
-| Open Sans (sans, variable) | `mem8YaGs126MiZpBA-U1UpcaXcl0Aw` | `https://fonts.gstatic.com/s/opensans/v44/mem8YaGs126MiZpBA-U1UpcaXcl0Aw.ttf` |
-| Montserrat (sans, variable) | `JTUSjIg1_i6t8kCHKm45xW5rygbi49c` | `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf` |
-| Poppins (sans) | `pxiEyp8kv8JHgFVrFJDUc1NECPY` | `https://fonts.gstatic.com/s/poppins/v24/pxiEyp8kv8JHgFVrFJDUc1NECPY.ttf` |
-| DM Sans (sans, variable) | `rP2Hp2ywxg089UriOZSCHBeHFl0` | `https://fonts.gstatic.com/s/dmsans/v17/rP2Hp2ywxg089UriOZSCHBeHFl0.ttf` |
-| Nunito (sans, variable) | `XRXV3I6Li01BKof4MuyAbsrVcA` | `https://fonts.gstatic.com/s/nunito/v32/XRXV3I6Li01BKof4MuyAbsrVcA.ttf` |
-| Raleway (sans, variable) | `1Ptug8zYS_SKggPN-CoCTqluHfE` | `https://fonts.gstatic.com/s/raleway/v37/1Ptug8zYS_SKggPN-CoCTqluHfE.ttf` |
-| Oswald (display, variable) | `TK3iWkUHHAIjg75GHjUHte5fKg` | `https://fonts.gstatic.com/s/oswald/v57/TK3iWkUHHAIjg75GHjUHte5fKg.ttf` |
-| Bebas Neue (display) | `JTUSjIg69CK48gW7PXooxW5rygbi49c` | `https://fonts.gstatic.com/s/bebasneue/v16/JTUSjIg69CK48gW7PXooxW5rygbi49c.ttf` |
-| Anton (display) | `1Ptgg87LROyAm0K08i4gS7lu` | `https://fonts.gstatic.com/s/anton/v27/1Ptgg87LROyAm0K08i4gS7lu.ttf` |
-| Playfair Display (serif, variable) | `nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU` | `https://fonts.gstatic.com/s/playfairdisplay/v40/nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU.ttf` |
-
-Variable fonts (most of the above) cover the full weight range (100–900) from a single URL — set `font.weight` in the clip. For the non-variable fonts (Poppins, Bebas Neue, Anton) the registered URL is weight 400; the SDK falls back gracefully when you request a bolder weight.
+The verified 12-font catalogue lives in [`shared/agent-core.md`](../shared/agent-core.md) (Fonts section) — the single copy, so it can't drift. Copy entries from there verbatim. Non-variable fonts in that table (Poppins, Bebas Neue, Anton) register at weight 400; the SDK falls back gracefully when you request a bolder weight.
 
 ### Sourcing more fonts
 

package/skills/shotstack/references/html5.md

@@ -82,7 +82,7 @@ The iframe renders under a strict Content-Security-Policy (`default-src 'none'`)
    ```
 2. **Use a system family** (`system-ui`, `Arial`, `Georgia`, …) — resolves in the render browser with no load.
 
-An unresolved family silently falls back to the browser default — the render won't fail, but the text won't be your font. For a single styled line, a `rich-text` asset (which *does* use `timeline.fonts[]`; verified catalogue in `references/fonts.md`) is simpler than a `data:` font embed.
+An unresolved family silently falls back to the browser default — the render won't fail, but the text won't be your font. For a single styled line, a `rich-text` asset (which *does* use `timeline.fonts[]`; verified catalogue in `shared/agent-core.md`) is simpler than a `data:` font embed.
 
 ## Sizing
 

package/skills/shotstack/references/onboarding.md

@@ -0,0 +1,71 @@
+# First render: discovery interview
+
+**The gate: do not compose an Edit until the user has answered the questions
+below (or explicitly said "just show me anything").** Setting up the CLI and
+key can proceed; writing the video cannot.
+
+"Render my first video" is not a specification. It says nothing about the
+subject, the content, the format or where the video will go. Neither does
+"set up Shotstack". If any of those are unstated, ask. A first video is only
+useful when it matches what the user is actually trying to make, and a short
+interview gets there faster than guessing.
+
+Skip the interview only when the user has stated what the video is (e.g.
+"make a 9:16 promo from the images in ./assets with the tagline X"), or has
+declined to answer.
+
+## The interview
+
+Ask conversationally, batched into one or two messages, and wait for the
+reply. Skip any question the project already answers (e.g. a Next.js
+e-commerce app full of product images answers question 2).
+
+1. **What should the video do?** Social clips, product or listing videos,
+   personalised outreach, in-app content, something else? Listen for the job,
+   not the feature.
+2. **What content or data exists?** Images, footage, audio or brand assets in
+   the project or at URLs; structured data (CSV, JSON, database, CMS) that
+   could drive repeated or personalised videos.
+3. **Where will the videos go?** Destination decides format: 9:16 for
+   TikTok/Reels/Shorts, 1:1 or 4:5 for feeds, 16:9 for YouTube/web. When in
+   doubt for social, default to 1080x1920 (9:16).
+4. **One video or many?** Both make fine first renders, but the composition
+   differs: pipelines should use merge fields from the start.
+
+## From answers to a first render
+
+- Compose ONE Edit JSON that answers the four questions. Make it something
+  worth keeping, not a minimal demo.
+- Use the user's real assets when they exist (host local files first:
+  `shotstack ingest upload <file> --watch`, then reference the returned URL).
+  If nothing is to hand, build from the Shotstack asset library
+  (`references/asset-library.md`) and motion-graphic snippets
+  (`references/html5-snippets.md`), matched to their stated use case.
+- Use their brand where it exists: colours, fonts and logos from the project
+  or their site rather than an invented look. Follow the house motion
+  language (`references/motion.md`).
+- If they chose "many": add merge fields (`{{ placeholder }}`) for the parts
+  that vary per video, and show one render with sample values.
+- Loop: compose, then `shotstack validate`, then `shotstack render edit.json
+  --env stage --watch`.
+
+## Wrapping up
+
+- Give two links, always: the rendered MP4 and a Studio link (`shotstack
+  studio <file> --no-open`, include the printed shotstack.studio URL). The
+  Studio link lets the user tweak the design in the browser without touching
+  JSON; say so.
+- Describe what they have in plain terms: a reusable template, free stage
+  renders, the same JSON in production via `--env v1`, merge fields for the
+  parts that vary. Don't surface validator warnings or internal caveats
+  unless something is actually broken.
+- End by offering to take the next step towards what they said in the
+  interview, concretely, not a generic list. They wanted a data-driven
+  pipeline: offer to wire the template to their data source and render a
+  batch now. They mentioned their own footage: offer to upload it and swap it
+  in. One sharp offer beats five open-ended suggestions.
+
+## Tone
+
+Brisk, concrete and curious about the user's project. Batch questions, don't
+drip-feed. One good clarifying question beats three generic ones.

package/skills/shotstack/shared/agent-core.md

@@ -266,7 +266,26 @@ Use **custom Google Fonts via `timeline.fonts[]`**. System fonts (`Arial`, `Helv
 
 **CRITICAL: Do NOT construct or fabricate Google Fonts URLs from memory.** Google rotates them (`v26 → v31 → ...`) and the hash filenames change with each version. Any URL you reconstruct from training data is almost certainly a 404. **Use ONLY the verified entries below, copied verbatim.**
 
-See `references/fonts.md` for how to source fonts from the Studio SDK catalogue and the built-in fallback fonts.
+### Verified font catalogue (12 fonts)
+
+Paste the **url** into `timeline.fonts[].src`, paste the **family** into `asset.font.family`.
+
+| Font (style) | family (use in `font.family`) | url (use in `timeline.fonts[].src`) |
+|---|---|---|
+| Inter (sans, variable) | `UcCo3FwrK3iLTfvlaQc78lA2` | `https://fonts.gstatic.com/s/inter/v20/UcCo3FwrK3iLTfvlaQc78lA2.ttf` |
+| Roboto (sans, variable) | `KFOmCnqEu92Fr1Me5WZLCzYlKw` | `https://fonts.gstatic.com/s/roboto/v50/KFOmCnqEu92Fr1Me5WZLCzYlKw.ttf` |
+| Open Sans (sans, variable) | `mem8YaGs126MiZpBA-U1UpcaXcl0Aw` | `https://fonts.gstatic.com/s/opensans/v44/mem8YaGs126MiZpBA-U1UpcaXcl0Aw.ttf` |
+| Montserrat (sans, variable) | `JTUSjIg1_i6t8kCHKm45xW5rygbi49c` | `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf` |
+| Poppins (sans) | `pxiEyp8kv8JHgFVrFJDUc1NECPY` | `https://fonts.gstatic.com/s/poppins/v24/pxiEyp8kv8JHgFVrFJDUc1NECPY.ttf` |
+| DM Sans (sans, variable) | `rP2Hp2ywxg089UriOZSCHBeHFl0` | `https://fonts.gstatic.com/s/dmsans/v17/rP2Hp2ywxg089UriOZSCHBeHFl0.ttf` |
+| Nunito (sans, variable) | `XRXV3I6Li01BKof4MuyAbsrVcA` | `https://fonts.gstatic.com/s/nunito/v32/XRXV3I6Li01BKof4MuyAbsrVcA.ttf` |
+| Raleway (sans, variable) | `1Ptug8zYS_SKggPN-CoCTqluHfE` | `https://fonts.gstatic.com/s/raleway/v37/1Ptug8zYS_SKggPN-CoCTqluHfE.ttf` |
+| Oswald (display, variable) | `TK3iWkUHHAIjg75GHjUHte5fKg` | `https://fonts.gstatic.com/s/oswald/v57/TK3iWkUHHAIjg75GHjUHte5fKg.ttf` |
+| Bebas Neue (display) | `JTUSjIg69CK48gW7PXooxW5rygbi49c` | `https://fonts.gstatic.com/s/bebasneue/v16/JTUSjIg69CK48gW7PXooxW5rygbi49c.ttf` |
+| Anton (display) | `1Ptgg87LROyAm0K08i4gS7lu` | `https://fonts.gstatic.com/s/anton/v27/1Ptgg87LROyAm0K08i4gS7lu.ttf` |
+| Playfair Display (serif, variable) | `nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU` | `https://fonts.gstatic.com/s/playfairdisplay/v40/nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU.ttf` |
+
+Variable fonts cover the full weight range (100–900) from a single URL — set `font.weight` on the clip. For a font not listed: copy an entry **verbatim** from the Studio SDK catalogue (~400 fonts) at <https://github.com/shotstack/shotstack-studio-sdk/blob/main/src/core/fonts/google-fonts.ts>, or open the font on <https://fonts.google.com>, view the CSS, and copy the exact `.ttf` URL from the `@font-face` `src`. Never hand-edit the version or hash segments.
 
 ### Usage example
 
@@ -297,7 +316,7 @@ The `font.family` value MUST match the `family` column in the table above (it's
 ## Top 5 mistakes
 
 1. **Reverse track order.** `tracks[0]` is the TOP layer, not the bottom. Captions go in early tracks; backgrounds go in late tracks.
-2. **System fonts.** `Arial`, `Helvetica`, `Times New Roman`, etc. are not installed. Use Google Fonts via `timeline.fonts[]` (preferred) or one of the built-in fonts in `references/fonts.md`.
+2. **System fonts.** `Arial`, `Helvetica`, `Times New Roman`, etc. are not installed. Use Google Fonts via `timeline.fonts[]`, copied verbatim from the verified catalogue in the Fonts section.
 3. **Captions fill the whole frame.** A `rich-caption` clip without `width`, `height`, and `fit: "none"` covers the entire output. Use a named preset from `references/caption.md`.
 4. **`<text>` inside an SVG asset.** Raw `<text>` is unsupported. Use a `rich-text` asset for any text content; reserve SVG for shapes only.
 5. **Composing custom caption styles when presets exist.** The five named presets (Nico, Kai, Kapow, Lovely Little Lychee, Rizz) cover the common styles. Use one verbatim from `references/caption.md` unless the user asks for something specific.