@shotstack/cli 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Command-line interface for the Shotstack video rendering API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/shotstack/shotstack-cli",

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/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.