@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/story-telling/SKILL.md

@@ -0,0 +1,222 @@
+---
+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

@@ -0,0 +1,130 @@
+---
+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

@@ -0,0 +1,119 @@
+---
+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

@@ -0,0 +1,98 @@
+---
+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

@@ -0,0 +1,87 @@
+---
+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.