@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/story-telling/SKILL.md

@@ -1,222 +0,0 @@
----
-name: story-telling
-description: "Story video expert. Use when the user asks to make an explainer video, a story video, a reel or a short, a narrated video from an article, a cartoon explainer, or asks to add a scene, change a voice, redo an image, switch to vertical, or re-render an existing story. Also triggers for Sarvam AI voiceover, bulbul TTS, FLUX 2 image generation, flux-2-pro/edit reference photos, and AICUT narration timing. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "marketcalls/story-telling"
----
-
-# Story Telling Video Skill
-
-## 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.
-
-
-## Critical Rules
-
-1. **story.json is the single source of truth.** Script, image prompts, voice,
-   fonts, colours, stat cards and measured durations all live in
-   `public/<slug>/story.json`. The composition reads it through
-   `calculateMetadata`. Never hardcode a duration, size or asset path in a component.
-2. **Audio drives length.** `npm run generate` measures every voice file and
-   writes `durationInFrames` back. `durationInFrames` and
-   `audioDurationInSeconds` are outputs, never hand edited. To lengthen a video,
-   change the words or raise `outro.durationInFrames`, never stretch a scene.
-3. **Show the narration before generating.** Voices and images cost money and
-   take minutes. A wrong figure caught in review is free.
-4. **Facts come only from the given context.** Nothing inferred, rounded or
-   assumed. When the source contradicts itself, prefer body text over headline
-   and tell the user which reading was used.
-5. **Spell numbers as words in narration, digits only on stat cards.** "thirty
-   four thousand crore" is spoken, `Rs 34,387 cr` is shown.
-6. **Never name a real person in an image prompt.** Use a reference photo the
-   user owns through the edit model, or describe the person generically.
-   In an edit prompt the likeness clause comes first, scene direction second.
-7. **One art style for the whole story.** `style.artPrompt` is prepended to
-   every image prompt. That single string is what makes the frames feel like
-   one film rather than a stock photo set.
-8. **Animate with `useCurrentFrame()` and `interpolate()`,** inline in the
-   `style` prop, always clamped. CSS transitions, CSS animations and Tailwind
-   animation classes render as still frames.
-9. **Use `scale`, `translate`, `rotate` CSS properties,** not `transform`
-   strings, with `output: "perceptual-scale"` on scale animations.
-10. **Respect the video safe area.** 80px from the sides, 100px from top and
-    bottom at 1080 wide, scaled by composition width. Headlines at least 84px,
-    supporting text at least 44px on the same scale. Take sizes from
-    `getLayout()`, never typed pixel constants.
-11. **Image ids are global across the story,** not per scene. A reused id
-    silently overwrites a frame, and zod will not catch it.
-12. **Skip work that already exists.** The generator skips any voice or image
-    already on disk. Delete exactly what should change and rerun; `--force`
-    should be rare.
-13. **Never commit `.env`, a key, or generated media.** `story.json` regenerates
-    everything else, and keys must never reach a settings file or a skill file.
-
-## Modular Rule Files
-
-| Rule File | Topic |
-|---|---|
-| [story-json](rules/story-json.md) | The schema field by field, full example, cheap edit recipes |
-| [narration](rules/narration.md) | Script shape, word budget per duration, TTS-safe phrasing, stat cards |
-| [voices](rules/voices.md) | Complete bulbul voice catalog, 11 languages, pace and temperature, font pairing |
-| [images](rules/images.md) | FLUX 2 models, prompt recipe, reference photos, likeness, real failure modes |
-| [models](rules/models.md) | Every model id, where it is configured, how to choose, cheap iteration loop |
-| [story-formats](rules/story-formats.md) | Format catalog with scene skeletons and stat placement |
-| [composition](rules/composition.md) | Remotion best practices the components follow |
-| [workflow](rules/workflow.md) | Commands, key verification, cost and timing, troubleshooting |
-| [pitfalls](rules/pitfalls.md) | The fourteen common mistakes, plus both checklists |
-
-## Story Templates (in rules/assets/)
-
-Schema-validated starting points. Copy to `public/<slug>/story.json`, change
-`slug` and `compositionId`, rewrite the narration and prompts, then generate.
-
-| Format | Path | Length | Scenes | Images |
-|---|---|---|---|---|
-| Biography | `assets/biography/story.json` | 60s | 6 | 12, uses a reference photo |
-| Concept explainer | `assets/explainer/story.json` | 60s | 6 | 9, metaphor led |
-| Vertical short | `assets/reel/story.json` | 30s | 3 | 3, 1080x1920 |
-| Numbered list | `assets/listicle/story.json` | 60s | 6 | 7, numbered stat cards |
-| News or event | `assets/news/story.json` | 45s | 5 | 7, dated claims |
-| Myth versus fact | `assets/myth-buster/story.json` | 45s | 5 | 5, alternating |
-
-## Companion Skills
-
-| Skill | Use for |
-|---|---|
-| `story-setup` | First run: Node check, install, `.env`, key verification, version alignment |
-| `story-new` | Context to finished video, with a script review step |
-| `story-render` | Change one line, one image, the voice or the orientation, then re-render |
-
-## Pipeline
-
-```
-context (article, notes, a paragraph, a page already read)
-   |
-   |  npm run draft            OpenAI, optional. Or write story.json yourself.
-   v
-public/<slug>/story.json       script, image prompts, voice, style, stats
-   |
-   |  npm run generate         Sarvam voices, FLUX 2 images, measured durations
-   v
-public/<slug>/                 voice-0.wav ... image-1.jpg ... story.json updated
-   |
-   |  calculateMetadata        reads story.json, sets size, fps, durationInFrames
-   v
-npx -y @autoaiai/aicut@latest render
-```
-
-## Instructions
-
-0. **Check the pipeline exists before anything else.** These skills drive a
-   Remotion project. If the skills were installed on their own, `cli/` and
-   `src/` are not present yet and must be fetched once:
-
-   ```bash
-test -f cli/generate.ts && test -f src/Root.tsx && echo present || echo missing
-```
-```
-If missing, run the `story-setup` skill, which fetches the project with
-   `npx --yes degit marketcalls/story-telling story-telling`, installs
-   dependencies, creates `.env` and verifies the keys. Everything below runs
-   from the project root.
-1. Read the rules you need from the table above. `story-formats` first if the
-   shape is not decided, `narration` and `images` before writing anything.
-2. Confirm the environment: `.env` with `SARVAM_API_KEY` and `FAL_KEY`,
-   `npm install` done. If unsure, run the `story-setup` skill.
-3. Settle three things with the user if not already clear: orientation, length
-   in seconds, and whether reference photos are involved.
-4. Write `public/<slug>/story.json` from a template, or draft it with
-   `npm run draft` and then fix the facts by hand.
-5. Show the narration and wait for approval.
-6. `npm run generate -- --slug <slug>`.
-7. Preview with `npm run studio`, then render.
-8. Run the shipping checklist in `rules/pitfalls.md`.
-9. Report measured numbers: scene count, duration, image count, output path and
-   size, plus any assumption made about an ambiguous fact.
-```
-
-## Commands
-
-```bash
-npm run story    -- --slug big-bull --context ./article.md --seconds 60 [--render]
-npm run draft    -- --slug big-bull --context ./article.md --orientation vertical
-npm run generate -- --slug big-bull [--only voice|images] [--force] [--logs]
-npm run studio
-npm run typecheck
-npx -y @autoaiai/aicut@latest render
-```
-```
-`--context` accepts a file path or the text itself. Any folder under `public/`
-containing a `story.json` becomes a composition automatically, named after the
-slug in PascalCase, so nothing is registered by hand.
-```
-
-## Project Layout
-
-```
-.env                       keys and every model id
-cli/
-  env.ts                   loads .env from here and from the parent folder
-  service.ts               Sarvam, FLUX 2 text to image, FLUX 2 edit, OpenAI
-  draft.ts                 context  ->  story.json
-  generate.ts              story.json  ->  assets  ->  measured durations
-  story.ts                 draft, generate and optionally render in one go
-src/
-  Root.tsx                 story discovery, calculateMetadata
-  StoryVideo.tsx           scene timeline, audio, outro
-  components/              ImageLayer, Subtitle, StatCard, TitleCard, OutroCard
-  lib/schema.ts            zod schema shared by the CLI and the composition
-  lib/layout.ts            safe areas and type scale, both orientations
-  lib/fonts.ts             module level font loading
-public/<slug>/             story.json, voice-N.wav, image-N.jpg
-out/                       rendered mp4
-```
-
-## Worked Example
-
-`public/jhunjhunwala/story.json` is a complete 6 scene, 58.7 second landscape
-story: cartoon art, two reference photos restyled through `flux-2-pro/edit`,
-stat cards on four scenes, and a silent outro. Read it before writing a new one.
-Its media files are gitignored, so regenerate them with
-`npm run generate -- --slug jhunjhunwala`.
-
-## Example Usage
-
-`/story-telling turn this article into a sixty second explainer`
-`/story-new big-bull ./article.md 60 landscape`
-`/story-render big-bull images`
-
-## Source
-
-Rewritten for AICUT from [`marketcalls/story-telling`](https://github.com/marketcalls/story-telling)
-(MIT), .claude/skills/story-telling/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
-
-The repository holds 4 skills; this is the one its entry stands for.

package/skills/story-telling/rules/composition.md

@@ -1,130 +0,0 @@
----
-name: composition
-description: Remotion best practices the components follow, and how to extend them safely
----
-
-# Composition
-
-The Remotion rules this project is built on. Follow them when editing the
-components or adding a new one.
-
-## Animation
-
-Drive everything from `useCurrentFrame()` and `interpolate()`. CSS
-`transition`, CSS `animation` and Tailwind animation classes do not render:
-each frame is captured independently, so there is no wall clock for the browser
-to animate against.
-
-Keep the `interpolate()` call inline in the `style` prop. Studio can then edit
-the keyframes and write them back to the source; a value hoisted into a
-variable cannot be edited that way.
-
-```tsx
-// Good
-style={{
-  opacity: interpolate(frame, [0, 26], [0, 1], {
-    extrapolateLeft: "clamp",
-    extrapolateRight: "clamp",
-    easing: Easing.bezier(0.16, 1, 0.3, 1),
-  }),
-}}
-
-// Not editable in Studio, and drifts out of sync with the markup
-const opacity = interpolate(frame, [0, 26], [0, 1]);
-style={{ opacity }}
-```
-
-Use the `scale`, `translate` and `rotate` CSS properties rather than a
-`transform` string, and pass `output: "perceptual-scale"` on scale animations
-so growth reads as linear to the eye.
-
-Always clamp: `extrapolateLeft: "clamp", extrapolateRight: "clamp"`. Without it
-a value keeps running past its range and produces negative opacity or inverted
-scale at the edges of a sequence.
-
-## Interactive markup
-
-Wrap meaningful blocks in `Interactive.Div` with a `name`, and give
-`AbsoluteFill` and `Sequence` names too. Those names become the Studio timeline
-and the click-to-source targets. It costs nothing at render time.
-
-## Media
-
-- Audio and video: `<Audio>` and `<Video>` from `@remotion/media`.
-- Images: `<CanvasImage>` from `remotion`.
-- Animated formats: `<AnimatedImage>`.
-- Always reference `public/` files through `staticFile()`.
-
-Sarvam returns WAV. Remotion plays it directly, so there is no MP3 conversion
-step and no ffmpeg dependency anywhere in this project.
-
-## Duration
-
-`calculateMetadata` on the `<Composition>` fetches `story.json` and returns
-`width`, `height`, `fps`, `durationInFrames`, `defaultOutName` and the parsed
-story as props. The values on `<Composition>` itself are placeholders.
-
-```tsx
-const calculateMetadata: CalculateMetadataFunction<StoryVideoProps> = async ({
-  props,
-  abortSignal,
-}) => {
-  const response = await fetch(props.storyUrl, { signal: abortSignal });
-  const story = storySchema.parse(await response.json());
-  const { width, height } = DIMENSIONS[story.orientation];
-  return {
-    width,
-    height,
-    fps: story.fps,
-    durationInFrames: totalFrames(story),
-    defaultOutName: story.slug,
-    props: { ...props, story },
-  };
-};
-```
-
-Pass the `abortSignal` through to `fetch` so stale requests are cancelled when
-props change in the Studio.
-
-Scene lengths come from the audio measurement in `story.json`, so the timeline
-cannot drift. If you ever add `<TransitionSeries>`, remember the total shrinks
-by the overlap of each transition and the metadata must subtract it.
-
-## Layout
-
-`src/lib/layout.ts` derives every size from `width / 1080`:
-
-- Safe area: 80px sides, 100px top and bottom, scaled.
-- Headline at least 84px, supporting text at least 44px, scaled.
-- Subtitles sit `100 * scale` from the bottom, capped by `fitText` to the safe
-  width so a long word shrinks instead of overflowing.
-- Vertical frames get 4 word subtitle groups instead of 6, and the stat card
-  moves from top right to top centre.
-
-This is why one component serves both 1920x1080 and 1080x1920. When adding an
-element, take its sizes from `getLayout()` rather than typing pixel constants.
-
-## Fonts
-
-Load fonts at module level in `src/lib/fonts.ts`, never inside a component, and
-request only the weights and subsets used. A bare `loadFont()` pulls every
-weight and subset, which is dozens of network requests per family on every
-render. Asking for a weight a family does not ship throws at render time:
-Space Grotesk stops at 700.
-
-## Adding a composition
-
-Nothing to register. `Root.tsx` lists `getStaticFiles()`, finds every
-`<slug>/story.json` under `public/`, and creates one composition per story with
-the slug in PascalCase as the id. Drop a folder in, it appears in the Studio.
-
-## Rendering
-
-```bash
-npx remotion render <CompositionId> out/<slug>.mp4 --codec h264
-```
-
-Keep all `@remotion/*` packages on one version, with the `mediabunny` version
-that matches. A mixed install fails at bundling with an error like
-`export 'Logging' was not found in 'mediabunny'`. Check with
-`npx remotion versions`, fix with `npx remotion upgrade`.

package/skills/story-telling/rules/images.md

@@ -1,119 +0,0 @@
----
-name: images
-description: FLUX 2 models on fal.ai, prompt recipe, reference photos, and what actually goes wrong
----
-
-# Images
-
-Two models, both wrapped in `cli/service.ts`, both selected from `.env`.
-
-| Purpose | Env var | Default |
-|---|---|---|
-| Text to image | `FLUX_TEXT_MODEL` | `fal-ai/flux-2-pro` |
-| Restyle a reference photo | `FLUX_EDIT_MODEL` | `fal-ai/flux-2-pro/edit` |
-
-Other text to image endpoints, roughly best to fastest: `fal-ai/flux-2-max`,
-`fal-ai/flux-2-pro`, `fal-ai/flux-2`, `fal-ai/flux-2-flex`,
-`fal-ai/flux-2/turbo`, `fal-ai/flux-2/flash`. Each has a matching `/edit`
-endpoint. Use `flash` while iterating on prompt wording, then switch back.
-
-## Text to image
-
-```ts
-await generateImage({
-  prompt,                              // artPrompt + scene prompt, joined by the generator
-  path: "public/slug/image-1.jpg",
-  imageSize: { width: 1920, height: 1080 },   // or 1080x1920 for vertical
-  logs: true,
-});
-```
-
-`image_size` takes an explicit `{width, height}` or a preset such as
-`landscape_4_3`. The generator always passes explicit pixels matched to the
-composition, so nothing is cropped at render time.
-
-## Editing a reference photo
-
-The edit model needs public URLs, so local files are uploaded to fal storage
-first. `uploadToFal` does that once per reference and caches the URL.
-
-Pass more than one photo of the same person when you have them. The model sees
-the face from several angles and the likeness holds across far more frames:
-
-```json
-{ "id": 9, "reference": ["face", "portrait"], "prompt": "Keep his face ..." }
-```
-
-```ts
-const url = await uploadToFal("../photo/portrait.png");
-await editImage({
-  prompt,
-  imageUrls: [url],
-  path: "public/slug/image-9.jpg",
-  imageSize: { width: 1920, height: 1080 },   // "auto" keeps the input ratio
-});
-```
-
-`"auto"` is accepted by the edit endpoint only, never by text to image. Prefer
-explicit pixels: a portrait reference at `"auto"` produces a portrait frame,
-which `objectFit: cover` then crops through the subject's face. The generator
-tries explicit size first and falls back to `"auto"` only if the endpoint
-rejects it.
-
-## Prompt recipe
-
-Final prompt = `style.artPrompt` + `". "` + the scene's `prompt`.
-
-Keep the style string in `story.json`, never in the scene prompt. The scene
-prompt describes subject, action, setting, light and mood, and nothing else.
-
-```
-subject doing something, in a place, with this light, this mood
-```
-
-Good: "A small neat stack of vintage Indian rupee notes and a few coins on a
-wooden table beside a leather ledger and a fountain pen, single warm desk lamp,
-dramatic shadows, sense of a tiny beginning."
-
-## Likeness
-
-To keep a real person recognisable through the edit model, say so explicitly:
-
-> Keep his face, moustache, spectacles and Indian features clearly
-> recognisable, but make him look younger, in his mid twenties, in a plain
-> white shirt. Place him ...
-
-Without that clause the model drifts to a generic face within one or two
-sentences of scene description. One reference photo can drive many frames with
-different age, wardrobe and setting: upload once, reuse the URL.
-
-Never put a real person's name in a prompt. Either supply a reference photo the
-user owns, or describe the person generically ("a veteran investor in a black
-Nehru jacket").
-
-## What goes wrong in practice
-
-- **Garbled signage.** FLUX paints text-like shapes even with "no text, no
-  lettering, no numbers" in the style string. Compose so boards, screens and
-  posters sit at the frame edges where the crop and vignette hide them.
-- **Western default faces.** Crowd and background characters drift western
-  unless ethnicity is stated in the style string, not just the scene prompt.
-- **Unprocessable Entity.** A transient fal error. The wrapper retries with
-  backoff; a single retry usually clears it.
-- **Aspect mismatch after an orientation change.** Images are generated at the
-  composition size. Change `orientation` and every jpg is stale: delete them
-  and rerun. Voices are unaffected.
-- **Safety filter.** `FLUX_SAFETY_TOLERANCE` runs "1" strictest to "5" most
-  permissive; the default is "2". Raise it only when a legitimate prompt is
-  being blocked, and never to produce content of a real person that they did
-  not consent to.
-
-## How many images
-
-Two per scene is the default: each gets half the scene, cross fades over 22
-frames, and a slow Ken Burns push that alternates direction so consecutive
-scenes do not feel mechanical. One image per scene is calmer and cheaper.
-Three or more in a 10 second scene flickers.
-
-At 12 images a 60 second story is the bulk of the cost. Draft the prompts, show
-them to the user, then generate.

package/skills/story-telling/rules/models.md

@@ -1,98 +0,0 @@
----
-name: models
-description: Every model the pipeline can use, where it is configured, and how to choose
----
-
-# Models
-
-Nothing is hardcoded. Every model id is read from `.env` by `cli/env.ts` and
-pushed into `cli/service.ts` through `setModels()`. Changing a provider version
-is an edit to one line of `.env`.
-
-| Purpose | Variable | Default |
-|---|---|---|
-| Narration | `SARVAM_MODEL` | `bulbul:v3` |
-| Default voice | `SARVAM_SPEAKER` | `shubh` |
-| Default language | `SARVAM_LANGUAGE` | `en-IN` |
-| Text to image | `FLUX_TEXT_MODEL` | `fal-ai/flux-2-pro` |
-| Reference restyle | `FLUX_EDIT_MODEL` | `fal-ai/flux-2-pro/edit` |
-| Image safety filter | `FLUX_SAFETY_TOLERANCE` | `2` |
-| Image format | `FLUX_OUTPUT_FORMAT` | `jpeg` |
-| Story drafting | `OPENAI_MODEL` | `gpt-4.1` |
-
-`story.json` overrides `.env` for anything it sets: `.env` holds the defaults,
-the story holds the decisions for that particular video.
-
-## Narration, Sarvam AI
-
-| Model | Voices | Notes |
-|---|---|---|
-| `bulbul:v3` | 37 | Default. `temperature`, 2500 characters, 30+ voices. |
-| `bulbul:v2` | 7 | Legacy. `pitch` and `loudness`, 1500 characters. Different voice names. |
-
-Switching to v2 also means switching the speaker: see `voices.md`.
-
-## Images, FLUX 2 on fal.ai
-
-Text to image, roughly best to fastest:
-
-| Model | Use for |
-|---|---|
-| `fal-ai/flux-2-max` | Hero frames, thumbnails, anything held on screen long |
-| `fal-ai/flux-2-pro` | The default. Strong quality at a sane price |
-| `fal-ai/flux-2` | Base model, cheaper than pro |
-| `fal-ai/flux-2-flex` | When you want to tune steps and guidance |
-| `fal-ai/flux-2/turbo` | Bulk background frames, softer detail |
-| `fal-ai/flux-2/flash` | Prompt iteration only, then switch back |
-| `fal-ai/flux-2/klein/9b`, `.../klein/4b/base` | Small open models |
-
-Every one of those has a matching `/edit` endpoint for reference photos:
-`fal-ai/flux-2-pro/edit`, `fal-ai/flux-2-max/edit`, `fal-ai/flux-2/turbo/edit`,
-and so on. Always pair the edit endpoint with the text model, otherwise the
-reference frames and the scenery frames end up in visibly different styles.
-
-There are also LoRA gallery endpoints such as
-`fal-ai/flux-2-lora-gallery/digital-comic-art` and
-`.../ballpoint-pen-sketch`. These lock a look far harder than a prompt can, so
-they are worth it when a series needs to be visually identical across many
-videos.
-
-Workflow that saves money: set `FLUX_TEXT_MODEL=fal-ai/flux-2/flash`, generate
-all images, look at them, fix the prompts in `story.json`, then delete the jpgs,
-switch back to pro or max and regenerate.
-
-## Drafting, OpenAI
-
-Any chat completions model with JSON mode. Verified present on this account at
-the time of writing:
-
-```
-gpt-5.5      gpt-5.5-pro   gpt-5.4      gpt-5.4-mini  gpt-5.4-nano
-gpt-5.2      gpt-5.1       gpt-5        gpt-5-mini    gpt-5-nano
-gpt-4.1      gpt-4.1-mini  gpt-4.1-nano gpt-4o        gpt-4o-mini
-o3           o3-mini       o4-mini
-```
-
-Re-check rather than trusting this list:
-
-```bash
-curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" \
-  | python3 -c "import sys,json;print('\n'.join(sorted(m['id'] for m in json.load(sys.stdin)['data'])))"
-```
-
-Drafting is one call per story and is the cheapest step by far, so a stronger
-model here is good value. It is also entirely optional: writing `story.json`
-by hand produces better narration and removes any risk of invented facts.
-
-## Adding a provider
-
-`cli/service.ts` is the only file that talks to an API. To swap in a different
-TTS or image provider:
-
-1. Add a wrapper function with the same shape as `generateVoice` or
-   `generateImage`, writing to the same output path.
-2. Add its model id to the `models` object and to `cli/env.ts`.
-3. Document it in `.env.example`.
-
-Nothing in `src/` changes: the composition only ever reads `story.json` and the
-files in `public/<slug>/`.

package/skills/story-telling/rules/narration.md

@@ -1,87 +0,0 @@
----
-name: narration
-description: Writing the spoken script, word counts, and TTS-safe phrasing for Sarvam bulbul
----
-
-# Narration
-
-The script is the video. Artwork supports it, it does not carry it.
-
-## Length
-
-At `pace: 1.05` on bulbul:v3, English narration runs at roughly 165 words per
-minute. Budget:
-
-| Target | Words | Scenes |
-|---|---|---|
-| 30 seconds | 80 to 90 | 3 |
-| 60 seconds | 160 to 175 | 6 |
-| 90 seconds | 250 to 265 | 9 |
-
-Per scene: 24 to 32 words, which lands between 8 and 11 seconds. Shorter than
-20 words and the cut feels abrupt; longer than 35 and the images go stale.
-
-Measured example, the six scene Jhunjhunwala story: 168 words produced 55.6
-seconds of audio, plus a 3.1 second outro card for 58.7 seconds total.
-
-If the total comes in short and a round minute matters, add outro frames rather
-than padding the script. Never stretch a scene past its audio: the subtitles
-are spread across the scene duration and would drift out of sync.
-
-## Shape
-
-- Scene 1 is a hook: the single most striking fact, stated flat, no throat
-  clearing. Not "today we will look at".
-- The middle scenes each carry exactly one idea. If a scene needs two numbers,
-  it is two scenes.
-- The last narrated scene lands the payoff the hook promised.
-- The outro card is a title, not a sentence. Three to five words.
-
-## TTS-safe phrasing
-
-Sarvam reads what you write, literally.
-
-- Spell numbers as words: "thirty four thousand crore", "nineteen eighty five",
-  "two hundred fifty times". Digits get read inconsistently. If you must keep
-  digits, the Sarvam docs ask for commas above four digits, "10,000" not "10000".
-- No hyphens, ampersands, brackets, slashes, asterisks or emoji. Write "and",
-  and split the sentence instead of using a dash.
-- Avoid abbreviations that are read as words: write "CA" only if you want the
-  letters, write "chartered accountant" if you want the phrase.
-- For API and code names, write them the way they should sound: "client dot
-  place order", not "client.placeorder()".
-- Percentages: "six point five percent" is safer than "6.5%".
-- Keep sentences under about 25 words. Long clauses make the model rush.
-
-## Facts
-
-- Every claim comes from the given context. Nothing is inferred, rounded or
-  "commonly known".
-- When the context conflicts with itself, prefer the body text over the
-  headline, and tell the user which figure was used. The Jhunjhunwala article
-  says 34,384 crore in the title and 34,387 crore in the body: the narration
-  uses 34,387 and the title card keeps the headline figure.
-- Dates carry their source: "Forbes, three July twenty twenty one", not "today".
-- Do not describe a living person's current state from a dated source.
-
-## Stat cards
-
-The card shows what the voice cannot: exact digits.
-
-- `value` short and numeric: `Rs 5,000`, `250x`, `6.50%`, `Rs 34,387 cr`.
-- `label` upper case, under seven words, and carries the qualifier or date:
-  `NET WORTH, FORBES, 3 JULY 2021`.
-- At most one card per scene, and not on every scene. Four cards in six scenes
-  is already busy.
-- A card that repeats the narration word for word is noise. It should add the
-  precision the spoken line deliberately rounded off.
-
-## Subtitles
-
-Subtitles are generated from `narration`, not authored separately. The text is
-split into word groups (6 landscape, 4 vertical) spread evenly across the scene.
-This tracks the voice closely enough without word level timestamps, which is why
-scene duration must equal audio duration exactly.
-
-Consequence: one very long word or a 40 word scene makes groups flash by. Keep
-scenes inside the word budget and the subtitles stay readable.