@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/riffkit/references/details.md

@@ -1,153 +0,0 @@
-## Details by step
-
-What a step of **The flow** needs beyond what it says there, for an agent that makes the calls itself (the CLI or HTTP). The routes are in "API reference".
-
-### Mode (step 0)
-
-| Mode | `mode` | What stays | What changes | Pick it when |
-|---|---|---|---|---|
-| **Adapt** | `adapt` (also what the API runs when `mode` is omitted) | The emotion formula: hook, rhythm, beats | The story, scenes, script, language | The user wants *their own* video that works like the winner |
-| **Swap** | `swap` | The source's camera, cuts, framing, action, timing, sound and frame shape | What the user names: the person (your character, if you pick one), a product, and whatever `content_anchor` names: the setting, an outfit, a line's wording | The user wants *this* video with their character in it ("the same video, but me", "keep every shot") |
-
-Swap rules (backend-enforced):
-- **A swap must change at least one thing**: a character (`character_ids`), a product that has images (`product_id`; a product without images changes nothing), a reference image (`reference_ids`; an outfit needs a person in the source), or a non-empty `content_anchor`. None of these → 400 whose `detail` is a plain localized sentence (en: "A swap needs at least one change: …"; the body carries no error code, so relay `detail` rather than matching on it). Checked for every swap source, before anything is analyzed or billed.
-- **The character is optional.** With no character the source's own person stays (their real face is in the output); there is no Auto person in swap. One task per character, like adapt; no character = one task. A picked character needs an approved avatar (`has_any_active_avatar=true`), same as adapt. If the user wants a *different* person, recommend picking a character: a person changed only by words in `content_anchor` has no reference image, so the face can differ between shots (and on Seedance 2.0 the voice stays the original's).
-- **Whose voice changes.** On engines that change voices (Seedance 2.5, MiniMax H3), a replaced person gets a new voice only on the lines they speak on camera; narration (heard, not seen) keeps the source's voice. To change the narration too, say so in `content_anchor`, e.g. "the narration also in the new person's voice" (vague wording may not be picked up). To keep every original voice, say "keep the original audio".
-- **Check the avatar before a paid swap with a character.** The swap takes the person's face, hair and build from the character's avatar image (`reference_image` in `GET /api/characters`; fetch `${BASE_URL}${reference_image}` with the session cookie, like a video's `file_url`). What works: one person, facing the camera, face large in the frame, plain background. The layout the Characters page recommends works too: one image with that person's chest-up close-up on the left and the same person head to toe on the right, same outfit (two large views, so the build and outfit are shown as well). What usually fails to replace the face in a close-up talking-head source is a sheet of many small poses, decorations or other people: the output keeps the original face and at most picks up the hair. When the avatar looks like that, suggest a new avatar in one of the layouts that work (uploaded on the Characters page, reviewed before it can be used) or another character, instead of retrying the swap.
-- **A character only counts if the source shows a person to replace.** For a template source the analysis is already known, so a swap whose only change is a character, of a source with no person in it, → 400 whose `detail` is a localized sentence (en: "This video shows no person to replace: …"): offer a product with images or a written change instead. A new upload / TikTok link isn't analyzed yet at submit, so the same rule is applied after its analysis (see Swap specifics). Either way nothing is billed.
-- **Never compressed**: the output is as long as the source, so the source must be within the render-duration cap (default 45s, see General constraints). A swap source's length is its **video stream's** length, measured the way the render engine measures it (a trailing audio tail doesn't count); for a template this can differ slightly from the analyzed length in `GET /api/formulas/{id}` → `extraction_summary.duration_seconds`. A longer source → 400 whose `detail` is a plain localized sentence stating both numbers (en: "This video is ~Ns, over the Ms limit. Please pick a video under Ms."; no error code in the body, so don't match on fixed text), including a template over the cap. For a template source, `GET /api/riffs/swap-quote` tells you the length, the price and whether it's over the cap before you submit (a source longer than one render window can bill slightly more than the quote; see Swap specifics).
-- **Ignored in swap** (accepted, not used — no need to strip them): `language` (the source's own language is kept), `product_visibility` (a product is on camera or absent), `bgm_mode`, `video_ratios` (the source's frame shape is kept, one video per character). `user_hint` still feeds a new source's analysis.
-- `content_anchor` means **"what to change"**: empty = only the picked character / product change. A product still needs to be attached (`product_id`); to show particular images, send their ids as `product_image_ids` (an @-mention says how one is used).
-- **Engine: Seedance 2.5 is the recommended swap engine** (it gives the best swap result). Read it from `GET /api/settings` → `swap_recommended_video_backend` (`seedance25`, or `null` when this deployment doesn't offer that engine: then recommend nothing). For a paid account it is also the swap default (an omitted `video_backend` lands on Seedance 2.5 720p); a free-tier swap lands on Seedance 2.0 Fast 480p, the free default in every mode and the cheapest free swap (50/s, vs 60/s on Seedance 2.0 480p), and a free-tier account still gets 403 on Seedance 2.5. When the quote's `fits` is false, offer a pair from its `alternatives`. Adapt mode has no recommended engine.
-- In the app the two modes are labelled **Adapt** and **Swap** (zh 「改编」/「翻拍」); use those names when you point the user at the screen.
-- A finished swap video can be reframed into extra **vertical** ratios with `POST /api/pipeline/backfill` (billed at the same swap / reframe rates below). A swap submits one video per character in the source's own frame shape, so `video_ratios` doesn't fan it out at submit.
-
-### Source (step 1)
-
-| Source | Param | When |
-|---|---|---|
-| **Analyzed template** | `formula_id` | The user wants an existing template, or has riffed this source before — **skips analysis, fastest** (analysis is free either way; skipping it saves the wait, not credits) |
-| **TikTok link** | `tiktok_url` | The user dropped a viral link; the server auto-downloads the video + extracts BGM |
-| **A file you can send** | `video` | The file is on this machine (≤100MB, and within the render-duration cap — see General constraints; a longer source is rejected, not trimmed) |
-| **A file only the user has** | `upload_id` | The video is on the user's phone or computer: `POST /api/riffs/uploads` makes a link where they add it, and `GET /api/riffs/uploads/{upload_id}` tells you when it is `ready` |
-
-- Template candidates: `GET /api/formulas?status=analyzed&template_type=pipeline`. `visibility=public` are platform-curated templates (usable across scopes, prefer recommending them). A template with `analysis_prompt_is_latest=false` can't be riffed or swapped: the quote and the submit refuse it with a 400 (nothing is created or billed). If it's your own template (`visibility=scope`), call `POST /api/formulas/{id}/refresh-analysis`, wait for that analyze task to complete (while it runs the template isn't `analyzed`, so a riff is rejected with 400), then riff. A `visibility=public` platform template can't be refreshed from your account (404): recommend a current one instead, or riff the original from its TikTok link or an upload (analysis is free).
-- **The same TikTok link already analyzed with current analysis, in your scope or as a public template, is reused** (free, faster). The reused link acts like `formula_id`: `user_hint` is ignored and the response is `mode: "generate"`. If the only earlier analysis is stale, the link is analyzed fresh automatically; the agent needs no special handling.
-- **The same video file sent again is reused too**: a `video` whose exact bytes your scope already has a current analyzed template of acts like `formula_id` (`mode: "generate"`, no new template, no analysis; a Swap's first section and its price are that template's). Sent with a different `user_hint`, it is analyzed fresh. A file cut or exported again is a different file. An `upload_id` is always analyzed.
-- The sources are **mutually exclusive**; exactly one must be provided (else 400).
-- A video the user already made with Riffkit can't be named as a source by its id. To swap it, the user downloads it and uploads the file as the source, like any other upload.
-
-### Character, product, placement, language (steps 2 and 3)
-
-Each can be left alone on its default; the agent may suggest where helpful but **never blocks**. (In swap mode language / visibility / ratios don't apply, and at least one change must be named: see Mode.)
-
-**Character (default Auto)**
-- By default `character_ids` is empty = **Auto mode**: no digital human bound, SD2 generates the on-camera person. This is the product default, not an edge case.
-- **The agent may proactively pick/suggest a fitting character** — when the user expresses account/persona intent ("post it to my health account", "use my creator persona"), read `GET /api/characters` and match by `persona` feel + `gender` / `age_range`, then suggest one. **Only suggest characters with `has_any_active_avatar=true`** (a `false` character can't generate video yet: its current avatar is still in the automatic review, usually under a minute, was rejected, or it has no avatar. The user can wait, switch to an approved avatar from the character's history, retry the review, or upload a different image on the Characters page).
-- If the user expresses no account intent, **proceed silently on Auto** — don't interrupt just to make them choose.
-- Multiple characters: only pass several when the user explicitly says "make one for each of these characters" (one task per character).
-
-**Product (default none)**
-- By default `product_id` is empty = `no_product` mode: pure content, the caption never mentions a product name or product CTA, the whole video just runs the template's emotion formula. Good for growth / relatability / educational content.
-- To place a product:
-  - **Existing product** → `GET /api/products`, take the `product_id`.
-  - **New product** → `POST /api/products` once the user has confirmed its name and description (never save product details the user hasn't confirmed). Its pictures need the product to exist, so it is created before they are added.
-- Product images: clean product photos / app screenshots (no watermark, no browser chrome, subject centered); at least one clean image noticeably lifts a placement. An image is always a file: send it yourself (`POST /api/products/{id}/images`; if the original has noise you may crop/clean it first), or, when only the user has it, make an upload link for it (`POST /api/image-uploads` with the `product_id`). A link to an image is not accepted. Riffkit names and describes each image from the picture within seconds (a `name` you send is kept). With the product on camera a video uses as many of its images as fit, in the product's order; to use particular ones send their ids as `product_image_ids`, and to say how one is used, @-mention it (`mentions`).
-
-**Reference images (default none)**
-- Pictures the video should show that are not the product: an outfit, a place, a prop. They live in the account's reference library (`GET /api/references`); a new one is a file you send (`POST /api/references`) or the user adds through an upload link (`POST /api/image-uploads` without a `product_id`). One of the account's product images can be used as a reference too (its `media.id`).
-- Send the ids as `reference_ids`, in the order to use them. To say who wears one, where or when, write `@` plus a short name in `content_anchor` and list it in `mentions`: `{token: "@Red dress", target: "reference", id: <reference id>}`; a mention can also point at a product image in use (`product_image`) or a character (`persona`, the character's id).
-- How many fit: the references and the product images in use share what one render of the engine takes (`GET /api/settings` → `video_backends[].reference_per_call`, less one, and less one more with a character). Over it the submit is a 400 that says how many to remove.
-- A picture with a real face in it: a Seedance engine takes it only after its own review (`seedance_review`: `pending` / `ok` / `refused`); `refused` means that engine can't use the image (the submit says so), MiniMax H3 can. A flat-lay or hanger shot avoids the question.
-- In a Swap a reference image counts as a change (an outfit needs a person in the source to wear it). Several outfits or places: the ones you @-mention are used where the sentence says; an unmentioned second one is used only where the source itself changes outfit or scene.
-
-**Visibility `product_visibility` (only meaningful with a product; default on_camera)**
-
-| Value | Meaning | Best for |
-|---|---|---|
-| `on_camera` (default) | Product appears as a physical object on screen (character holds / scans / shows it) | Food / cosmetics / small physical goods / packaging as the core hook |
-| `off_camera` | Product never enters frame; conveyed only via subtitles / voiceover / caption text | Apps / websites / SaaS / services / non-portable goods |
-
-When `product_id` is empty this field is ignored and the backend derives `no_product`. **The caller may not pass `no_product` directly** (only the two literals on_camera / off_camera are accepted). The script and visual staging differ greatly across modes, so when a product is bound always state the value and the reason at the confirmation step.
-
-**Language (default en)**
-- Candidates from `GET /api/languages` (currently `en` / `es` / `pt` / `id` / `de` / `fr` / `it` / `ja` / `zh-CN`, in picker order). Trust the endpoint, don't hardcode.
-
-**content_anchor (optional creative direction) + user_hint (optional hook hint)**
-- `content_anchor` is the agent's highest-value contribution: it may proactively draft one for the user to review (see `## content_anchor drafting framework`). If the user doesn't want one, leave it empty — the video still generates.
-- `user_hint` feeds only a **new source's** analysis ("this popped off on the twist at 0:03"); it's ignored when a `formula_id` is chosen, so don't send it then.
-
-### Price and plan (steps 5 and 6)
-
-Restate the plan with its price from `GET /api/riffs/quote`, asked with the same mode, source, engine, tier, character count, (adapt) ratio count and delivery you are about to submit. Mention the balance only when the quote's `fits` is false, and then offer an engine from `alternatives` that fits (or a template from `fitting_templates`):
-
-```
-Ready to riff:
-├── Mode: [Adapt / Swap]
-├── Source: [template name / TikTok link / the user's video]
-├── Character: [name / Auto (AI-generated person); swap: a name / keep the original person]
-├── Product: [name + visibility / none]
-├── Language: [en / es / pt / id / de / fr / it / ja / zh-CN; swap: the source's own]
-├── Price: [quote `credits` ÷ 100, already the whole batch (one video per character; one with no character or when keeping the original person); "about" when `exact` is false, when you asked for more than one ratio (each extra ratio is re-priced from the finished video), or for a swap source longer than one render window. Made in sections: the first section's price, and about the whole (`sections_estimate.whole_credits` ÷ 100). No number when `source_seconds` is null (`credits` is then a minimum, not a price): say the length couldn't be read and the charge follows the real length; if `probe` is `busy`, ask the quote again shortly. Same for a local file whose length you can't measure]
-└── content_anchor: [drafted creative direction / none; swap: what changes besides the person]
-```
-
-When the user says "submit / generate / riff" → call `POST /api/riffs`.
-- If a **new product** was chosen, first `POST /api/products` (+ upload images serially) to get the `product_id`, then include it in the riff.
-- Insufficient balance returns **HTTP 402** (structured `insufficient_credits`) → handle per "Billing & balance".
-- A submit can also get **HTTP 429** with `detail.code == "server_busy"` (and a `Retry-After: 30` header) when the servers are at capacity. Nothing was created or billed: wait about 30 seconds, then submit once more. Other 429s are rate or daily limits (see Common errors).
-
-### Progress (step 8)
-
-- The whole riff shares one `batch_id` (the analyze task and the chained generation task both carry it) → poll `GET /api/tasks/batch/{batch_id}`.
-- Every **30 seconds**; cap a single poll loop at **15 minutes** (pipeline tops out around 8 min, 2× tolerance), then pause and tell the user.
-- **Swap on a Seedance engine** first sends each source clip through the video vendor's content review before any rendering starts; the first swap of a source can wait several minutes there. Verdicts are remembered per clip content, so later swaps of the same, unchanged source reuse them (a clip already refused fails the task at once, without a new review); if the source file itself changed, its clips are reviewed again. If the review refuses a clip (or the video engine refuses its format), the task fails **before any video second is billed** and the `error` names the window's seconds and a code in parentheses. That `error` is a fixed Chinese sentence whatever the request language: restate it in the user's language (keep the code verbatim) and offer what the message offers: a different source.
-- Summarize, don't echo every poll: "running 2m30s, currently writing the script," roughly once a minute (put `current_step` in plain words; never quote the raw code).
-- Failure handling: on `failed`/`dead`, read `error` to locate the cause, **don't auto-retry**, tell the user and let them decide; if a task stays `queued` for over 2 minutes, the servers are busy: say the video will start as soon as a slot frees up, and keep polling.
-- **Insufficient credits mid-riff** (a new-source riff clears the submit gate, then the real duration proves too costly — since v1.1.3 a low-balance riff usually gets an instant `402` at submit instead: TikTok URLs via a metadata duration probe, uploads via the on-disk file's real duration; this can still happen when the duration couldn't be read at submit, when the real duration differs from the probe, or when the balance dropped between submit and analysis, because the balance is checked again before analysis and again before generation): the analyze task carries `result.auto_generate_error == "insufficient_credits"` and `result.insufficient_credits` = the same structured 402 payload (`required_credits` / `available_credits` / `topup_url`). This means **no video was generated** — even when `status == "completed"` (the analysis finished but generation was skipped). Treat it like a 402: relay `topup_url` verbatim and tell the user to top up. Once they have, **retry that task** (`POST /api/tasks/{id}/retry`): a `failed` one (the check ran before analysis) runs again, within 24h; a `completed` one goes on from its saved analysis with everything it was submitted with (no second analysis, no wait for one; only the video is billed, as usual). While the balance is still short the retry answers `402` again; `409` `chain_resuming` = another retry is submitting it; `410` = its template was deleted, so submit again from the source. **Never report success on a riff whose analyze task carries this field.**
-
-### Delivery and files (step 9)
-
-`GET /api/assets?asset_role=final_reel&sort=created_desc&limit=10` (add `formula_id` / `character` to filter this run):
-
-1. **The video file** — `${BASE_URL}${file_url}`. This is the ONLY file path — there is **no** `/api/assets/{id}/download` sub-resource (it 404s; do not invent REST-style suffixes). The GET needs the same `Cookie: vee_session=<token>` as every API call, and must follow redirects (`curl -L`): in production it 302s to object storage. A cookie-less GET returns 401. For a link the user can open in their own browser, where your session cookie doesn't travel, call `GET /api/assets/{asset_id}/link`: its `url` opens the video without the cookie for 6 hours; say how long it works and that you can get a fresh one.
-2. **Suggested copy** — `caption` (hook → body → closing call-to-action folded into one paragraph) + `asset_hashtags`
-3. **Strategy recap** — which emotion formula this used, through which beat the product was felt, what the content_anchor did. To see what the engine actually "extracted / rewrote," call `GET /api/tasks/{task_id}/content`.
-4. **Next iteration** — next time tweak content_anchor / character / product combo; a richer template library (more `used_count` / `tags`) gives sharper picks.
-
-#### Using a finished video in Remotion or another code-made video
-
-When the user wants the clip inside their own Remotion composition (or any video rendered from code), download it to a local file first. Remotion reads a local file or a public URL, and the asset URL only answers with the session cookie, so don't hand it the URL directly:
-
-```bash
-curl -L -b "vee_session=<token>" "${BASE_URL}<sd_video_url or file_url>" -o clip.mp4
-```
-
-The first request needs the cookie; the redirect then lands on signed storage. Put `clip.mp4` in the project's `public/` folder and load it with `staticFile("clip.mp4")`.
-
-- **Clean master, no burned-in captions**: use `sd_video_url` when it's set. It is the render before post-processing: no burned-in captions, but the final mixed audio is already in it. It's only set when post-processing ran; when it's null, `file_url` is already that render. Use `file_url` when the user wants the captions kept, and then don't add a second set of captions on top. A swap is the exception: the source video's on-screen text is drawn into the swap's picture, so neither file is free of it. On the free plan `sd_video_url` is always null: the render before post-processing comes with a plan, and `file_url` carries the small Riffkit watermark. A plan removes the watermark from every video, earlier ones included.
-- **Frame shape**: choose it at submit to match the composition. Riffs take `video_ratios` (vertical `9:16` / `3:4` / `1:1` / `4:5`, any mix, or one of `16:9` / `4:3` / `21:9` alone); creation takes one `video_ratio`; a swap keeps the source's frame. A vertical video you already have can get more vertical ratios with `POST /api/pipeline/backfill`.
-- **Fixed length**: a creation video can be pinned with `duration_mode=fixed` + `duration_seconds` (4-45). A swap is exactly as long as its source; an adapt riff's length isn't fixed until it renders, so for a composition that needs an exact length use a creation video with `duration_mode=fixed`.
-- **Sound**: the video has ONE mixed audio track, voice and music together. In Remotion you can keep it, lower it or mute it as a whole (`volume` / `muted` on `<OffthreadVideo>`), but you can't take the music out and keep the voice. If the user adds their own music, tell them it will play over the music already in the clip.
-- Save the file into the user's own project; don't upload it to a third-party host unless the user asks.
-
----
-
-## General constraints
-
-| Dimension | Limit | Source |
-|------|------|------|
-| Source video (upload or TikTok link) | Upload ≤ **100 MB**; both ≤ the **render-duration cap** (`max_render_duration`, default **45 s**, runtime-adjustable, ceiling 90s) — the SAME single number that caps the riff output, not a separate limit; over the duration → 400 at submit for an upload (the file is also cleaned up); a TikTok link gets the same 400 when its length can be read up front, otherwise the link is accepted and the analyze task fails with the same "~Ns, over the Ms limit" message once the video has downloaded (nothing is generated or billed) | `POST /api/riffs` `video`/`tiktok_url`, `POST /api/formulas/analyze` |
-| Generated video length | Riffs (adapt / swap): ≤ **max_render_duration** (the same single cap as the source upload above). Creation videos: **4-45 s**, a separate fixed ceiling that does not follow `max_render_duration` (smart mode is also capped at what the balance affords; see `POST /api/creation/batch`) | engine render budget; creation: `POST /api/creation/batch` |
-| Swap source length | ≤ **max_render_duration** for every swap source (template, upload, link): a swap is never compressed, so the output equals the source length | `POST /api/riffs` `mode=swap` |
-| Image upload | ≤ **50 MB** each, `.jpg/.jpeg/.png/.webp`; ≤ **8 images** per product (free tier: 1) | product and reference images |
-| `content_anchor` / `user_hint` | ≤ **5000 chars** (over → `422`) | riffs / pipeline/batch / creation/batch |
-| riffs rate | **10 / 60 s** | `POST /api/riffs` |
-| Task concurrency | Shared worker pool, sized per server (not a per-account quota); overflow → `queued`; under heavy load a new submit gets `429` with `detail.code == "server_busy"` (`Retry-After: 30`) | server TaskRunner |
-| Generation time | pipeline **3-8 min** (empirical) | — |
-| Poll interval | every **30 s** | The flow, step 8 |
-| Daily credit cap | `daily_limit` from `GET /api/usage/credits` (`0` = unlimited; internal credits ÷100 for display) | adjustable by owner/admin |
-
-> BGM is picked by the backend (optionally steered with `bgm_mode` on an analyzed template) — the riff flow has no audio upload step.
-
----

package/skills/riffkit/references/errors.md

@@ -1,69 +0,0 @@
-## Task state machine
-
-| State | Meaning | Keep polling? |
-|------|------|----------|
-| `queued` | Submitted, waiting for a TaskRunner slot | ✅ |
-| `running` | Executing | ✅ |
-| `completed` | Output persisted; `result` carries asset_id | ❌ (fetch assets) |
-| `failed` | Normal failure (LLM error / API rate limit / …); `error` has the cause | ❌ (no auto-retry) |
-| `dead` | Stopped by an interruption it couldn't recover from on its own: a template analysis or a subtitle burn/reconcile cut off by a server restart, or a riff / creation / swap interrupted over and over. A riff, creation or swap caught by a single restart is NOT dead: it picks up where it stopped, with no extra credits, so keep polling while it shows `queued`/`running` | ❌ (offer a retry, available within 24 h of submission) |
-| `cancelled` | User cancelled | ❌ |
-
-```
-queued → running → completed
-                 ↘ failed / dead / cancelled
-```
-
----
-
-## Common errors
-
-| HTTP / error | Scenario | Handling |
-|-------------|------|------|
-| `401` unauthenticated | vee_session expired/missing | Re-run the device flow (`POST /api/skill/device/authorize` → user approves → poll `.../token`); see **Auth** |
-| `402` insufficient_credits | not enough to submit | Show the shortfall in display credits (internal ÷ 100) + relay `topup_url` verbatim, **no retry** |
-| `400` — not exactly one source | missing or multiple sources | Ensure exactly one of `video`/`tiktok_url`/`formula_id`/`upload_id` |
-| `400` — "This template needs an update before it can be used. …" (header `X-Refusal: template_outdated`) | `formula_id` names a template whose analysis is out of date (`analysis_prompt_is_latest=false`), on `POST /api/riffs`, `POST /api/pipeline/batch` or a quote; nothing created or billed | Your own template: `POST /api/formulas/{id}/refresh-analysis`, wait for it, then submit. A public one: pick a current template, or riff the original from its TikTok link |
-| `400` — `detail.error == "character_avatar_not_ready"` | a picked character's current avatar is still in review or was rejected (`reviewing` / `rejected` list the names), on any riff, swap or creation submit; nothing created or billed | Relay `message`. In review: wait about a minute and submit again. Rejected: another character, or the user switches to an approved avatar or uploads a new one on the Characters page |
-| `400` — "A swap needs at least one change: …" | `mode=swap` with no character, no product with images, no reference image and an empty `content_anchor` | Ask what should change: a character to put in, a product to place, a reference image to use, or a written change |
-| `400` — "This video shows no person to replace: …" | `mode=swap` naming only a character, from a template that shows no person | Offer a product with images or a written change, or another source |
-| `400` — video can't be used for a swap | `mode=swap` from a template that has no source video | Offer another template, or a new upload/link |
-| `400` — "Swapping one of your own finished videos is not available. Download the video and upload it as the source." | the request named one of the user's finished videos as the source (`source_asset_id`, a retired parameter: any value, in either mode, on `POST /api/riffs` or a quote); nothing created or billed | Send it without `source_asset_id`. Tell the user to download the video and upload it as the source (`video`), or offer a template or a TikTok link |
-| `400` — source video too long | the uploaded file, or a TikTok link whose length could be read at submit, runs longer than `max_render_duration` (the message states both numbers); in swap mode, also any template over the cap | Ask the user for a shorter video, or to trim it and upload the trimmed file |
-| `400` — "Only TikTok links are supported." | `tiktok_url` isn't on tiktok.com / www.tiktok.com / vm.tiktok.com / vt.tiktok.com, or it carries a port, a login part or a backslash | Ask the user for the TikTok share link of the video (Share → Copy link) |
-| `400` — TikTok link is not a specific video | `tiktok_url` points at a profile, photo post, Shop product page or live instead of one video: on tiktok.com the path has no `/video/` and isn't a `/t/` share link; for a `vm.`/`vt.` short link, this is where it redirects | Ask the user for the link of **one video**: one containing `/video/`, a `tiktok.com/t/…` share link, or a `vm.`/`vt.` short link |
-| `400` — required missing | name/description etc. not sent | Fill per the field tables; don't paper over with empty strings |
-| `400` — invalid language | a code not in the candidates | First `GET /api/languages` for candidates |
-| `400` — "`<field>` is not UTF-8 — it arrived as legacy-encoded bytes (GBK/Big5/Shift-JIS)…" | a multipart text field (`content_anchor` / `user_hint` on `POST /api/riffs`; the image's `name` / `description` on `POST /api/products/{id}/images`; `name` on `POST /api/references`; `name` on `POST /api/characters`; `name` / `user_hint` on `POST /api/formulas/analyze`) was typed into a non-UTF-8 console (Windows CJK default), which re-encoded it before curl sent it | Do **not** resend the same command: it fails the same way, and `chcp` alone doesn't fix it. Write the text to a UTF-8 file and pass it by reference: `-F "content_anchor=<'/tmp/anchor.txt'"` (see `POST /api/riffs`). Already doing that? Rewrite the file with an explicit UTF-8 encoding. Never switch a multipart endpoint to `json=`: its fields would be ignored |
-| `400` — "There was an error parsing the body" | a JSON body (e.g. `POST /api/products`) was not UTF-8 | Send JSON with your library's UTF-8 encoder (`requests.post(url, json=…)`, `fetch`/`axios`, `json.Marshal`); on Chinese Windows `cmd` run `chcp 65001` first; never build the body by hand with `data=` |
-| `422` — request validation | a JSON body without a required field (e.g. `creation/batch` without `content_anchor`, or with it empty or only spaces); a wrong type or an unsupported value (e.g. `product_visibility` / `duration_mode` outside the listed values, `duration_seconds` outside 4-45, `duration_mode=fixed` without `duration_seconds`); `content_anchor` / `user_hint` over 5000 chars | `detail` is a list of `{loc, msg, type}`: fix the field named in `loc` using the field tables, and don't resend the same body. A misspelled **optional** field gets no error at all (it's ignored), so check field names against the tables |
-| `413` file too large | over 100MB video / 50MB image | State the limit, recompress, re-upload |
-| `409` `upload_used` (with `formula_id` / `batch_id`) | `upload_id` on `POST /api/riffs` or a quote, for an upload already submitted once; nothing created or billed | Don't make a new link: follow that `batch_id`, or for another video from the same source send that `formula_id` once the template reads `analyzed` |
-| `409` — the video hasn't arrived / is being used by another submit (`upload_id`) | the upload link's page has no video in yet, or another submit of the same upload is running | Not arrived: ask the user to finish on the page, then `GET /api/riffs/uploads/{upload_id}`. In use: wait for that submit; don't send it twice |
-| `410` — the upload is gone (`upload_id`) | the link or its video ran out, or the account ended its links ("Sign out other devices", an assistant disconnected) | Make a new link (`POST /api/riffs/uploads`) |
-| `429` on `POST /api/riffs/uploads` | 10 unused uploads have a video in or arriving, or more than 6 links in 10 minutes | Use one of the uploads already in (`GET /api/riffs/uploads/{upload_id}`), or wait; don't loop |
-| `409` `price_changed` on `POST /api/assets/{asset_id}/continue` | the price or the video's progress changed since you quoted it; nothing started | Quote the new `credits` (÷100) and ask again |
-| `409` `confirm_needed` on `POST /api/assets/{asset_id}/continue` | the body had no `credits` or `delivered_through`; nothing started | Quote its `credits` (÷100), get the go-ahead, send both |
-| `409` `film_busy` / `film_complete` on `POST /api/assets/{asset_id}/continue` | part of the video is being made now / nothing is left to make | Busy: follow its batch and offer the next step when it's done. Complete: nothing to continue |
-| `409` `film_pending` on a subtitle `PUT` / `DELETE` / `burn` / `reconcile` | the video is made in sections and sections are still left | Captions wait for the whole video: continue it first, or leave them |
-| `410` `continue_expired` on `POST /api/assets/{asset_id}/continue` | past the video's `staged.finish_by` | Only a new video can be made |
-| `400` `not_sectioned` / `action_unavailable` / `invalid_action` on `POST /api/assets/{asset_id}/continue` | not a video made in sections, that action has no price now (e.g. `redo` before anything was delivered), or `action` isn't `next` / `rest` / `redo` | Read the video's `staged` block and offer only an action in `staged.prices` |
-| `403` `first_section_only` (`error` `subscription_required`) on `POST /api/assets/{asset_id}/continue` | an account held to the first section asked for `next` / `rest` | It can only `redo` the first section; handle as `403` subscription_required (Billing & balance) |
-| `403` `one_at_a_time` (`error` `subscription_required`) on a submit, a retry, a continue or a ratio backfill | a free-tier account already has a video in the making | Nothing started. Say a video is in progress; once `GET /api/tasks` shows it done, submit again (handle the plan side as `403` subscription_required, Billing & balance) |
-| `409` `film_delivered` on `POST /api/tasks/{task_id}/retry` | the first render of a video made in sections failed after it had delivered a section: a retry would replace the video | Continue the video instead (`POST /api/assets/{asset_id}/continue`) |
-| `410` on `POST /api/tasks/{task_id}/retry` (`detail` Chinese, or the request's language for a deleted video or template) | over 24 h since the task was first submitted, a riff / swap submitted before a Riffkit update that changed how riffs are built, or its video or template was deleted; nothing restarted or billed | Say in the user's language that this task can't be retried; offer a fresh submit of the same kind with the same options (see `POST /api/tasks/{task_id}/retry`) |
-| `409` on `POST /api/tasks/{task_id}/retry` (`detail` always Chinese) | the task's previous run hasn't finished shutting down | Wait about a minute, then retry once; still `409` → tell the user and check back later |
-| `400` on `POST /api/tasks/{task_id}/retry` (`detail` always Chinese) | the task isn't `failed`/`dead` (cancelled, completed, or already restarted by an earlier retry); nothing restarted or billed | Read the task's status and poll it; don't submit again |
-| `429` — `detail` is a plain sentence in the request's language: "Too many requests — slow down (max 10 per 60s)." (请求过于频繁… when the request asks for Chinese) | more than 10 submits in 60 s (counted separately for `POST /api/riffs`, `/api/creation/batch` and `/api/pipeline/batch`) | Wait about a minute, then submit once; don't loop |
-| `429` — `detail.code == "server_busy"` (header `Retry-After: 30`) | the servers are at capacity (any riff, creation, pipeline batch or backfill submit); nothing was created or billed | Tell the user the servers are busy, wait about 30 s, then submit once more; if it happens again, suggest trying later |
-| `429` — daily limit reached (`detail` names the limit and today's spend, already in credits) | today's spend has reached the daily cap (`daily_limit` in `GET /api/usage/credits`) | Relay the message. The cap resets at 00:00 UTC; in a team, the team owner can raise a member's cap; for a personal account, or a team owner's own cap, the user contacts Riffkit. Don't resubmit until the cap is raised or the day rolls over |
-| `429` — `detail.error == "free_cost_limit"` | this account's model spend that produces no video in the last `window_days` (analysis, subtitle alignment, automatic image descriptions and the like) is over its current allowance; it is checked when you start an analysis (a riff from a new upload or TikTok link, `POST /api/formulas/analyze`, `refresh-analysis`) | Not a short wait: offer to riff an already-analyzed template (`formula_id`). The allowance grows as the account generates paid videos. Its numbers are internal credits (÷ 100 for display) |
-| `500` / timeout | server error | Say try again later; if it recurs, report to the developers |
-| Task `failed` + error mentions "Seedance" | proxy / API failure | Surface the specific error, let the user decide |
-| Task `failed` + error says the video is ~Ns, over the Ms limit | a TikTok link whose length couldn't be read at submit turned out too long after download (riff or swap; nothing billed) | Same as the 400: ask for a shorter video, or a trimmed upload |
-| Swap task `failed` + `error` starts with 这条原片里没有可替换的人物 | only a character was named, but the source shows no person (nothing billed; checked before any review or render) | Offer a product with images or a written change, or another source |
-| Swap task `failed` + `error` starts with 这次翻拍没有指定任何改动 | nothing to change was left by the time the task ran, e.g. the product lost its images (nothing billed) | Offer a product with images, a character, or a written change |
-| Swap task `failed` + `error` names a window's seconds (原视频 A–B 秒) and a code in parentheses | the video vendor refused that source clip, in content review (没有通过平台的内容审核) or for its format (格式不符合视频引擎的要求, code `InvalidParameter.*`); nothing billed | Restate the message in the user's language (the `error` text is always Chinese; keep the code verbatim); offer another source. Retrying the same source fails the same way |
-| Task `queued` over 2 min | the servers are busy | Say "the servers are busy, your video will start as soon as a slot frees up" |
-
----

package/skills/riffkit/references/intents.md

@@ -1,29 +0,0 @@
-## Natural-language intent ↔ action map
-
-| Intent | Example | Action |
-|---------|-------------|-----------|
-| One-shot riff | "riff this link", "make me one from this video" | `POST /api/riffs` (settle Adapt or Swap first, the flow's step 0; then source + optional config; confirm before submit) |
-| Original / no source | "make an original ad, no reference", "just write me a video about X", "创作一条" | `POST /api/creation/batch` (creative direction REQUIRED — draft it with the user; price it with `GET /api/creation/quote`; confirm before submit) |
-| Riff a new viral | "why did this TikTok pop off — riff it for me" | `POST /api/riffs` (pass `tiktok_url`/`video` → analyze→generate) |
-| A video on the user's phone | "I have it on my phone", "can I send you my video" | `POST /api/riffs/uploads` → the user adds it on that page → `GET /api/riffs/uploads/{upload_id}` → `POST /api/riffs` with `upload_id` |
-| Run an existing template | "make one with template 3" | `POST /api/riffs` (pass `formula_id`) |
-| Same shots, my character | "put my character in this exact video", "keep the video, swap the person", "翻拍" | `POST /api/riffs` with `mode=swap` + a character + one source; `content_anchor` = what else changes |
-| Browse templates | "what templates are there", "which is hot lately" | `GET /api/formulas?status=analyzed&template_type=pipeline` (by `used_count` / `tags`) |
-| Drill into a template | "tell me about this one", "why recommend it" | `GET /api/formulas/{id}`, read `extraction_summary` |
-| Re-analyze a template / fix its hint | "this is stale", "the hook is actually at 0:05" | `PATCH /api/formulas/{id}` (`user_hint`, optional) → `POST /api/formulas/{id}/refresh-analysis` (your own templates; a stale public template → pick another) |
-| Add a product / image | "I have a new product", "add an image to the product" | Restate + confirm → `POST /api/products` → the image as a file: `POST /api/products/{id}/images` (serial), or `POST /api/image-uploads` with the `product_id` when only the user has it |
-| Show an outfit, a place or a prop | "make her wear this", "use this room", "here's the dress" | `GET /api/references` (pick by name and description) or add one (`POST /api/references` / `POST /api/image-uploads`) → `reference_ids` on the submit, with an @-mention when the text says where or how |
-| Pick language | "make it in Spanish", "switch language" | `GET /api/languages` for candidates → set `language` |
-| On / off camera / none | "should the product show", "I don't want a product, just growth" | Explain `product_visibility` (incl. no `product_id` = no_product) + recommend a value |
-| Check progress | "how's it going", "done yet" | `GET /api/tasks/batch/{batch_id}` or `GET /api/tasks/{id}` |
-| Get results | "give me the download link" | `GET /api/assets?asset_role=final_reel&...`, then `GET /api/assets/{id}/link` for a link the user can open |
-| Fix subtitles | "the captions are mistimed", "move the subtitles up", "change the caption text/color" | Subtitle editing loop: `GET/PUT /api/assets/{id}/subtitles` → `POST .../preview` (iterate) → `POST .../burn` once (free; see `### Subtitle editing`) |
-| Check balance / spend | "how much is left", "how much today" | `GET /api/usage/credits` → `available` / `daily_spent` (the caller's own spend since 00:00 UTC; ÷ 100 for display) |
-| Finish a video made in sections | "make the rest", "next part", "redo that section" | `GET /api/assets` → its `staged.prices` → confirm → `POST /api/assets/{asset_id}/continue` |
-| Stop a task | "stop it", "cancel" | `POST /api/tasks/{id}/cancel` (note no refund of what's charged) |
-| Retry | "try again", "re-run" | `POST /api/tasks/{id}/retry` (state the most it can cost, confirm first) |
-| Set a character's voice | "use my voice for this character", "lock her voice" | `POST /api/characters/{id}/voice-sample` (mp3/wav, 4-15s clean speech) — then automatic on every adapt riff / creation |
-
-**Routing principle:** when intent is ambiguous, ask — don't guess and proceed.
-
----

package/skills/saas-motion-video/SKILL.md

@@ -1,71 +0,0 @@
----
-name: saas-motion-video
-description: "Make a promo / motion video for a software product with AICUT, using the saas-motion-kit 7-stage process (brief → components → theme → storyboard → build → sound → deliver), the clean-or-imaginary component rule, the creative muscle (tone matrix, variety rules, component forge, transition atlas, variety audit) and the 101-theme gallery in docs/. Use when someone asks for a launch video, product promo, booth loop, feature reveal or social motion piece for an app, SaaS or developer tool. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "tugrawork-creator/saas-motion-kit"
----
-
-# saas-motion-video
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-You are the producer. The user is the creative director. Run the stages in order and **stop at every gate** for a human decision. Keep the user's taste in the loop; that is what makes the film feel human-made.
-
-**The one rule of this kit: no two films should feel like the same film.** Don't repeat effects, transitions or components (within the film, or from the user's recent films). Invent at least one new component per film. Decide the message and the tone before choosing any effect. Read `creative/README.md` before stage 4.
-
-## Before starting
-- The HyperFrames skills must be installed (`npx skills add heygen-com/hyperframes`). If `/hyperframes` is not available, ask the user to install them and restart the session.
-- Read `playbook/README.md`. Read each stage file when you reach that stage.
-
-## Stages
-
-1. **Brief** (`playbook/01-brief.md`). Ask at most four questions: the one message, the channel/format, the sound (music, SFX, voice or silent) and the truth source (a URL or docs). Also ask whether they have reference videos they love. For each one, run `python tools/breakdown.py <video> --id NN --creator … --url …` and credit it in `REFERENCES.md` (`templates/REFERENCES.md`, `creative/references.md`): borrow grammar, never assets. Write `BRIEF.md` from `templates/BRIEF.md`. **Gate:** the user confirms the brief.
-2. **Components** (`playbook/02-components.md`, `components/README.md`). If there is a URL, run `npx hyperframes capture`. Score the real UI and propose, per component, *real* or *imaginary*. Never invent capabilities, customers or statistics. **Gate:** the user approves the inventory.
-3. **Theme** (`playbook/03-theme.md`). Suggest 2–3 themes from `docs/themes/data/*.json` that fit the audience (read their `summary`, `fit` and `best_for`). Start from `python tools/pick_themes.py --tone <the brief's tone> --audience "<audience words>" --history ~/.motion-ledger.json`, which skips the themes of the user's last five films. Redraw each candidate's proof-moment frame in the user's brand as a quick HTML still. **Gate:** the user picks one.
-4. **Storyboard + creative pass** (`playbook/04-storyboard.md`, `creative/`). Write `STORYBOARD.md` from `templates/STORYBOARD.md`: first the **Message & tone** sentence ("I want to say ___ in a ___ tone, so the viewer feels ___"), then the **ledger** (one row per shot: entrance, transition, ease, direction, palette, camera, components, new component, sfx, notes), then the frames. Choose craft from `creative/tone-matrix.md`, transitions from `creative/transition-atlas.md` (plus HyperFrames' stock set), and forge at least one new component with `creative/component-forge.md`. Run `python tools/variety_audit.py STORYBOARD.md --history ~/.motion-ledger.json` and fix every warning, or mark a deliberate repeat as `motif:`. Then draw a one-page sketch sheet. Keep on-screen words to a minimum. **Gate:** the audit is clean (or every remaining warning is explained), and the stills read as a story with the sound off.
-5. **Build** (`playbook/05-build.md`). Hand off to the HyperFrames workflow (`/product-launch-video` for a URL-driven promo, `/general-video` for loops and custom pieces). Keep every frame seek-safe and deterministic. Run `lint`, `snapshot` and `check`. **Gate:** the user approves the preview.
-6. **Sound** (`playbook/06-sound.md`). Music-driven: build a beat grid first and cut on bars. SFX: use warm tuned timbres (`tools/warm_sfx.py`). Silent is a valid choice. **Gate:** the user approves the mix.
-7. **Deliver** (`playbook/07-deliver.md`). Render at 4K, then run `tools/deliver.sh` to downscale. For loops, run `tools/loop_check.py`. Report the actual duration, size and path. Record the film so the next one avoids it: `python tools/variety_audit.py STORYBOARD.md --history ~/.motion-ledger.json --append "<film>" --theme <NNN>`. Every few films, offer `python tools/history_report.py ~/.motion-ledger.json -o motion-history.html` so the user can see what they keep reaching for. **Gate:** the user checks it on the target screen.
-
-## Hard rules
-- Official logos only. Never redraw a brand mark.
-- For non-Latin characters, bundle `latin-ext` font subsets locally. Write uppercase text yourself instead of relying on CSS `text-transform` (which breaks Turkish i/İ).
-- No progress bars, no gradient text, no pure #000/#fff, no bounce or elastic easing on UI.
-- Fewer words. If the story needs reading, redesign the frame.
-- Credit every reference video by name and link (`REFERENCES.md` and `ref:<id>` in the ledger; the audit enforces it). Never put someone else's footage, frames or music in a film or the repo.
-- Every transition must answer "why this one, here?". No transition twice in a row, at least three transition families, one surprise every ~15 s.
-
-## Source
-
-Rewritten for AICUT from [`tugrawork-creator/saas-motion-kit`](https://github.com/tugrawork-creator/saas-motion-kit)
-(MIT), .claude/skills/saas-motion-video/SKILL.md. The method is that skill's own; the way it runs is AICUT's.