@autoaiai/aicut 0.1.7 → 0.1.11

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

@@ -0,0 +1,140 @@
+---
+name: pitfalls
+description: Common mistakes, and the checklist to run before generating and before shipping
+---
+
+# Pitfalls
+
+Ordered by how often they actually bite.
+
+## 1. Generating before the script is approved
+
+Voices and images cost money and take minutes. A wrong figure caught in the
+`story.json` review is free; caught after the render it costs the whole run.
+Always show the narration to the user before running `generate`.
+
+## 2. Editing durationInFrames by hand
+
+`durationInFrames` and `audioDurationInSeconds` are outputs, not inputs. The
+generator measures the real audio and writes them back. Hand editing them
+desynchronises the subtitles immediately, because subtitle groups are spread
+across the scene duration. If a scene feels too short, change the words.
+
+## 3. Padding a scene to reach a round duration
+
+Same failure. To make a 55 second story reach 60, raise
+`outro.durationInFrames`, which is silent and has no subtitles. Never stretch a
+narrated scene beyond its audio.
+
+## 4. Digits in narration
+
+"Rs 34,387 cr" is read unpredictably. Spell it: "thirty four thousand three
+hundred eighty seven crore". Digits belong on the stat card, which is exactly
+why the card exists.
+
+## 5. Naming a real person in an image prompt
+
+Either it is refused, or worse, it succeeds and produces a fabricated likeness.
+Use a reference photo the user owns with the edit model, or describe the person
+generically. This is a hard rule, not a style preference.
+
+## 6. Burying the likeness clause
+
+In an edit prompt, "keep his face, spectacles and features clearly
+recognisable" must come first, before the scene description. Put it last and
+the model drifts to a generic face.
+
+## 7. Changing orientation after generating
+
+Images are generated at the composition size. Flip `orientation` and every jpg
+is the wrong shape, and `objectFit: cover` crops through the subject. Delete
+the jpgs and rerun. Voices are unaffected, so pass nothing and let the skip
+logic keep them.
+
+## 8. Mixed Remotion versions
+
+The classic symptom is a bundling failure:
+`export 'Logging' was not found in 'mediabunny'`. Every `@remotion/*` package
+must be on one version, with the `mediabunny` version that release expects.
+`npx remotion versions` to check, `npx remotion upgrade` to fix.
+
+## 9. Loading fonts wrong
+
+`loadFont()` with no options pulls every weight and subset, dozens of requests
+per family on every render. Requesting a weight a family does not ship throws
+at render time: Space Grotesk stops at 700. Load at module level, never inside
+a component, and always pass `weights` and `subsets`.
+
+## 10. CSS animation
+
+`transition`, `animation` and Tailwind animation classes render as a still
+frame. Every frame is captured independently, so there is no wall clock. Drive
+motion from `useCurrentFrame()` and `interpolate()`.
+
+## 11. Forgetting to clamp interpolate
+
+Without `extrapolateLeft: "clamp", extrapolateRight: "clamp"` values keep going
+past their range: negative opacity, inverted scale, text sliding off frame at
+the edges of a sequence.
+
+## 12. Text in the platform-unsafe zone
+
+Vertical videos lose the bottom of the frame to platform UI. Keep everything
+meaningful above the bottom 260px, and inside the safe area from `getLayout()`
+rather than typed pixel constants.
+
+## 13. Reusing an image id
+
+Ids are global across the story, not per scene. Two images sharing id 4 means
+one silently overwrites the other. The zod schema does not catch this; the
+symptom is a repeated frame.
+
+## 14. Committing generated media or keys
+
+`public/**/*.wav|mp3|jpg|png` is gitignored on purpose: `story.json`
+regenerates all of it. Never commit `.env`, and never paste a key into
+`.claude/settings.local.json` permission rules where it is stored in plain text.
+
+## 15. Editing story.json while a generate run is in flight
+
+An image run can take half an hour. `generate` used to write its whole
+in-memory copy back at the end, so any edit made meanwhile was silently
+discarded: stat cards added during the run simply vanished from the file and
+from the render. It now re-reads the file and merges back only
+`durationInFrames` and `audioDurationInSeconds`. Still, prefer to finish
+editing before starting a long run, and verify a change landed by reading the
+file back rather than trusting that you wrote it.
+
+## 16. Cross fades that dip through black
+
+If the outgoing image finishes fading out at the exact frame the next one
+starts fading in, both sit at zero opacity and the transition flashes black.
+The two ramps have to overlap: fade the outgoing image out over the same window
+the incoming one fades in over, not over its own final frames. `ImageLayer`
+does this, but the same trap applies to any transition added later.
+
+## Checklist before generating
+
+- [ ] Every figure in the narration traces to the given context
+- [ ] Numbers spelled as words in narration, digits only on stat cards
+- [ ] No hyphens, ampersands, brackets or emoji in any narration string
+- [ ] 24 to 32 words per scene
+- [ ] No real person named in any image prompt
+- [ ] Image ids unique across the whole story
+- [ ] `outro.imageId` points at an image that exists
+- [ ] `orientation` matches the target platform
+- [ ] `style.artPrompt` names the medium, the line, the palette and the people
+- [ ] Font in `style` covers the narration's script
+
+## Checklist before shipping
+
+- [ ] `npm run typecheck` clean
+- [ ] `npx remotion versions` reports all packages correct
+- [ ] Watched end to end with sound, not just scrubbed
+- [ ] Checked a frame in the middle of an image transition, not only mid scene
+- [ ] Re-read story.json after any long generate run, to confirm edits survived
+- [ ] Subtitles land with the voice on the last scene, where drift shows first
+- [ ] No garbled text visible in any frame
+- [ ] Faces consistent across every scene that uses the same reference
+- [ ] Sources and dates in the narration match the context
+- [ ] Output duration and file size reported to the user accurately

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

@@ -0,0 +1,108 @@
+---
+name: story-formats
+description: Story format catalog with scene skeletons, stat placement and art direction per format
+---
+
+# Story formats
+
+Pick the format first: it decides the scene count, where the stat cards go and
+what the outro says. Ready made starting points live in `assets/`.
+
+| Format | Template | Best length | Scenes |
+|---|---|---|---|
+| Biography | `assets/biography/story.json` | 60s | 6 |
+| Concept explainer | `assets/explainer/story.json` | 60s | 6 |
+| Vertical short | `assets/reel/story.json` | 30s | 3 |
+| Numbered list | `assets/listicle/story.json` | 60s | 6 |
+| News or event | `assets/news/story.json` | 45s | 5 |
+| Myth versus fact | `assets/myth-buster/story.json` | 45s | 5 |
+
+Copy a template to `public/<slug>/story.json`, change `slug` and
+`compositionId`, rewrite the narration and prompts, then generate.
+
+## Biography
+
+The arc that made the Jhunjhunwala video work.
+
+| Scene | Job | Stat |
+|---|---|---|
+| 0 | Hook: the end state as a number, and where it started | starting figure |
+| 1 | Origin: the moment or person that started it | none |
+| 2 | First move: the first real bet and what it returned | first return |
+| 3 | Setback or contrarian turn | none |
+| 4 | The big win, with the multiple | the multiple |
+| 5 | Where it ended up, sourced and dated | final figure |
+
+Art direction: one recurring character across the scenes. Use a reference photo
+through the edit model so the face stays the same, and vary age, wardrobe and
+setting per scene. Alternate character frames with object or place frames so it
+does not feel like a slideshow of one person.
+
+## Concept explainer
+
+| Scene | Job |
+|---|---|
+| 0 | The symptom the viewer already recognises |
+| 1 | Name the thing, plainly |
+| 2 | The mechanism, part one |
+| 3 | The mechanism, part two |
+| 4 | What changes when it moves |
+| 5 | What the viewer should now do or watch |
+
+Stats belong on scenes 1 and 4: the current value of the thing, and its effect.
+Art direction: metaphor over literal. A lever, a valve, a dam, a set of scales.
+Avoid charts as artwork, since the stat card already carries the number.
+
+## Vertical short
+
+Three scenes, about 30 seconds, `orientation: "vertical"`.
+
+| Scene | Job |
+|---|---|
+| 0 | Hook in the first three seconds, stated as a claim |
+| 1 | The one piece of evidence |
+| 2 | The turn, plus a reason to follow |
+
+Rules that differ from landscape: subtitles group 4 words, not 6; the stat card
+sits top centre; keep the title card to two lines. Put nothing important in the
+bottom 260px, where platform UI overlays sit.
+
+## Numbered list
+
+Scene 0 sets the promise ("five things ..."), scenes 1 to N carry one item
+each, and the last scene closes. Every item scene gets a stat card whose value
+is the item number or its headline figure, so the viewer can track position.
+Keep item scenes the same length: uneven items make a list feel disorganised.
+
+## News or event
+
+| Scene | Job |
+|---|---|
+| 0 | What happened, and when |
+| 1 | The number that makes it matter |
+| 2 | Background needed to understand it |
+| 3 | Who is affected |
+| 4 | What happens next, and by when |
+
+Every claim carries its date in the narration, not only on the card. News
+stories age: a video that says "today" is wrong within a day, one that says
+"on the third of July" stays correct.
+
+## Myth versus fact
+
+Alternate: myth stated flat, then the correction with the number. Use the
+accent colour on the fact scenes only, so the visual rhythm matches the
+argument. `style.accent` red for myths and green for facts is heavy handed:
+better to keep one accent and let the stat card carry the correction.
+
+## Choosing length
+
+| Platform | Orientation | Length | Scenes |
+|---|---|---|---|
+| YouTube | landscape | 60 to 90s | 6 to 9 |
+| YouTube Shorts, Reels, TikTok | vertical | 30 to 45s | 3 to 5 |
+| LinkedIn, X | landscape | 45 to 60s | 5 to 6 |
+| Website hero | landscape | 20 to 30s | 2 to 3, often no narration |
+
+Scene count is roughly seconds divided by ten. `npm run draft` applies exactly
+that rule and clamps between 3 and 10.

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

@@ -0,0 +1,143 @@
+---
+name: story-json
+description: The story.json schema, field by field, with a complete example
+---
+
+# story.json
+
+One file describes a whole video. It lives at `public/<slug>/story.json` and is
+validated by `src/lib/schema.ts` (zod) on both sides: the CLI refuses to
+generate an invalid story, and `calculateMetadata` refuses to render one.
+
+## Top level
+
+| Field | Type | Notes |
+|---|---|---|
+| `slug` | lowercase-hyphen string | Folder under `public/`. Also the default output name. |
+| `compositionId` | PascalCase string | Id in the Studio and in `remotion render`. |
+| `orientation` | `landscape` \| `vertical` | 1920x1080 or 1080x1920. Drives image size and type scale. |
+| `fps` | number | 30 unless there is a reason. |
+| `title` | object | Opening card. `eyebrow`, `headline`, `subline`. |
+| `voice` | object | `speaker`, `pace`, `temperature`, `languageCode`. |
+| `style` | object | `artPrompt`, `accent`, `background`, `displayFont`, `textFont`. |
+| `scenes` | array | One per voice file. See below. |
+| `outro` | object or null | Silent closing card after the narration. |
+| `references` | map | Name to local photo path, relative to the project root. |
+| `music` | object or null | `file` in `public/<slug>/`, and `volume` 0 to 1. |
+
+## Scene
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | number | 0 based. Becomes `voice-<id>.wav`. |
+| `narration` | string | 24 to 32 words. See `narration.md`. |
+| `images` | array | One or two. Two cross fade inside the scene. |
+| `stat` | object or null | `value` (digits) and `label` (upper case, under seven words). |
+| `audioDurationInSeconds` | number | Written by the generator. Do not hand edit. |
+| `durationInFrames` | number | Written by the generator. Do not hand edit. |
+
+## Image
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | number | Unique across the whole story. Becomes `image-<id>.jpg`. |
+| `prompt` | string | Scene direction only. The house style is prepended automatically. |
+| `reference` | string or array | Optional. One key from `references`, or several. Switches to the edit model. |
+
+Image ids are global, not per scene, because the outro points at one by id and
+because a frame can be reused in more than one scene.
+
+Passing several references holds a likeness far better than one, because the
+model sees the face from more than one angle:
+
+```json
+{ "id": 9, "reference": ["face", "portrait"], "prompt": "Keep his face ..." }
+```
+
+## Voice
+
+```json
+"voice": {
+  "speaker": "shubh",
+  "pace": 1.05,
+  "temperature": 0.6,
+  "languageCode": "en-IN"
+}
+```
+
+- `pace` 0.5 to 2.0 on bulbul:v3. 1.05 is a natural narration pace. Raise it to
+  fit more words into a fixed length, but past about 1.2 it starts to sound rushed.
+- `temperature` 0.01 to 2.0, bulbul:v3 only. 0.6 is stable. Higher is more
+  expressive and more likely to produce artefacts.
+- `languageCode` is BCP-47: `en-IN`, `hi-IN`, `ta-IN`, `te-IN`, `kn-IN`,
+  `ml-IN`, `mr-IN`, `bn-IN`, `gu-IN`, `pa-IN`, `od-IN`. Match the font: use
+  `AnekDevanagari` for Hindi or Marathi.
+
+## Style
+
+`artPrompt` is the single most important field for a coherent video. It is
+prepended to every image prompt. Be explicit about medium, line, colour and
+the people in frame:
+
+```json
+"artPrompt": "flat vector cartoon illustration, bold clean black outlines, vibrant saturated colours, expressive caricature faces, warm Indian skin tones, simple graphic shapes, subtle cel shading, modern editorial cartoon poster style, no text, no lettering, no numbers, no watermark, no signature"
+```
+
+Fonts available in `src/lib/fonts.ts`: `BricolageGrotesque`, `Poppins`,
+`Inter`, `SpaceGrotesk`, `PlayfairDisplay`, `AnekDevanagari`. Add a family
+there to make it selectable. `SpaceGrotesk` stops at weight 700, the others
+carry 800.
+
+## Minimal example
+
+```json
+{
+  "slug": "repo-rate",
+  "compositionId": "RepoRate",
+  "orientation": "vertical",
+  "fps": 30,
+  "title": {
+    "eyebrow": "IN SIXTY SECONDS",
+    "headline": "What the repo rate really does",
+    "subline": "The lever behind your EMI"
+  },
+  "voice": { "speaker": "shubh", "pace": 1.05, "temperature": 0.6, "languageCode": "en-IN" },
+  "style": {
+    "artPrompt": "flat vector cartoon illustration, bold outlines, vibrant colours, no text, no lettering",
+    "accent": "#7FD1FF",
+    "background": "#04060A",
+    "displayFont": "BricolageGrotesque",
+    "textFont": "Poppins"
+  },
+  "references": { "founder": "../photo/founder.jpg" },
+  "scenes": [
+    {
+      "id": 0,
+      "narration": "Every loan you hold is priced off one number that a committee in Mumbai resets a few times a year. Most borrowers never see it move.",
+      "stat": { "value": "6.50%", "label": "REPO RATE, FEB 2026" },
+      "images": [
+        { "id": 1, "prompt": "A vast marble central bank hall seen from below, tall pillars, a single lit desk at the centre, cool morning light" },
+        { "id": 2, "reference": "founder", "prompt": "Keep the face and features recognisable. Standing at a bank counter looking at a loan statement, warm interior light" }
+      ]
+    }
+  ],
+  "outro": {
+    "headline": "One number, every EMI",
+    "subline": "FOLLOW FOR MORE",
+    "imageId": 1,
+    "durationInFrames": 92
+  },
+  "music": null
+}
+```
+
+## Editing an existing story
+
+- Changed a `narration` string: `npm run generate -- --slug <slug> --only voice`.
+  The voice file is regenerated only with `--force`, so delete that one
+  `voice-N.wav` first, or pass `--force` and accept regenerating all of them.
+- Changed an `image.prompt`: delete that `image-N.jpg` and rerun `generate`.
+- Added a scene: give it the next `id`, give its images unused ids, rerun
+  `generate`. Existing files are skipped, so only the new assets are billed.
+- Changed `orientation` after generating: every image is now the wrong shape.
+  Delete the jpgs and rerun, the voices are unaffected.

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

@@ -0,0 +1,114 @@
+---
+name: voices
+description: Complete Sarvam bulbul voice and language catalog, with picking guidance and per-language font pairing
+---
+
+# Voices and languages
+
+Model `bulbul:v3` unless `SARVAM_MODEL` says otherwise. Speaker names are
+lowercase and case sensitive: `Shubh` fails, `shubh` works.
+
+## bulbul:v3 speakers
+
+37 voices. All work with every supported language.
+
+| Male | Female |
+|---|---|
+| shubh (default) | ritu |
+| aditya | priya |
+| rahul | neha |
+| rohan | pooja |
+| amit | simran |
+| dev | kavya |
+| ratan | ishita |
+| varun | shreya |
+| manan | roopa |
+| sumit | tanya |
+| kabir | shruti |
+| aayan | suhani |
+| ashutosh | kavitha |
+| advait | rupali |
+| anand | |
+| tarun | |
+| sunny | |
+| mani | |
+| gokul | |
+| vijay | |
+| mohit | |
+| rehan | |
+| soham | |
+
+Picking a voice:
+
+- `shubh` is the safe default: neutral Indian English, works for finance,
+  technology and news explainers.
+- Use a female voice when the source or the brand voice is female, or simply to
+  differentiate a series. `ritu` and `priya` are the closest female equivalents
+  to `shubh` in tone.
+- Keep one voice per series. Switching voices between parts of the same series
+  reads as a production error.
+- Test before committing to a long story: generate scene 0 only, listen, then
+  generate the rest. Deleting one wav and rerunning costs one call.
+
+## bulbul:v2 speakers
+
+Only relevant if `SARVAM_MODEL=bulbul:v2`. v2 rejects v3 speaker names.
+
+- Female: anushka, manisha, vidya, arya
+- Male: abhilash, karun, hitesh
+
+## Languages
+
+`languageCode` is BCP-47 and must be one of:
+
+| Code | Language | Font to pair |
+|---|---|---|
+| `en-IN` | Indian English | any Latin family |
+| `hi-IN` | Hindi | `AnekDevanagari` |
+| `mr-IN` | Marathi | `AnekDevanagari` |
+| `bn-IN` | Bengali | add a Bengali family to `fonts.ts` |
+| `gu-IN` | Gujarati | add a Gujarati family |
+| `kn-IN` | Kannada | add a Kannada family |
+| `ml-IN` | Malayalam | add a Malayalam family |
+| `od-IN` | Odia | add an Odia family |
+| `pa-IN` | Punjabi | add a Gurmukhi family |
+| `ta-IN` | Tamil | add a Tamil family |
+| `te-IN` | Telugu | add a Telugu family |
+
+The subtitles render the `narration` string exactly as written, so a non-Latin
+script needs a font that covers it. `src/lib/fonts.ts` currently ships Latin
+families plus `AnekDevanagari` (Devanagari and Latin). For any other script,
+add the family there with the right `subsets` before generating, otherwise the
+subtitles render as boxes while the audio is perfectly fine.
+
+Code mixing works: Hindi narration with English product names in Latin script
+is read correctly by `hi-IN`, and `AnekDevanagari` covers both scripts.
+
+## Tuning
+
+| Field | Range | Effect |
+|---|---|---|
+| `pace` | 0.5 to 2.0 | 1.05 is natural narration. Above 1.2 sounds rushed. Below 0.9 drags. |
+| `temperature` | 0.01 to 2.0 | v3 only. 0.6 stable, 1.0+ more expressive but more artefacts. |
+| `speech_sample_rate` | 8000 to 48000 | 24000 default. Higher only helps if the final mix is high quality. |
+
+Not available on v3: `pitch`, `loudness`, `enable_preprocessing`. Those are v2
+only and are silently ignored, which is why `cli/service.ts` branches on the
+model rather than always sending them.
+
+## Limits
+
+- 2500 characters per request on v3, 1500 on v2. One scene is 150 to 220
+  characters, so a scene never hits the limit. The generator throws before
+  calling the API if a narration is too long.
+- There is no word timestamp output, which is why subtitles are spread evenly
+  across the scene rather than word aligned. Keep scenes inside the word budget
+  in `narration.md` and this stays imperceptible.
+
+## Fixing a voice that reads something wrong
+
+1. Rewrite the text, do not fight the model. "CA" becomes "chartered
+   accountant", "6.5%" becomes "six point five percent", "RARE" becomes "Rare".
+2. Delete just that file: `public/<slug>/voice-3.wav`.
+3. Rerun `npm run generate -- --slug <slug> --only voice`. Everything else is
+   skipped, and the new duration is measured and written back automatically.

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

@@ -0,0 +1,105 @@
+---
+name: workflow
+description: Commands, environment, cost and timing, and troubleshooting
+---
+
+# Workflow
+
+## Setup, once
+
+```bash
+npm install
+cp .env.example .env      # then fill in SARVAM_API_KEY and FAL_KEY
+```
+
+`cli/env.ts` reads `.env` from the project root and from the parent folder, so
+a shared bootcamp-level `.env` also works. Keys in the project file win.
+`SARVAM_API_KEY` and `SARVAM_KEY` are both accepted.
+
+Check the keys before a long run:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" https://api.openai.com/v1/models \
+  -H "Authorization: Bearer $OPENAI_API_KEY"
+curl -s -X POST https://api.sarvam.ai/text-to-speech \
+  -H "api-subscription-key: $SARVAM_API_KEY" -H "Content-Type: application/json" \
+  -d '{"text":"key test","language_code":"en-IN","speaker":"shubh","model":"bulbul:v3"}' \
+  -o /dev/null -w "%{http_code}\n"
+```
+
+fal has no free ping. Posting an empty body to the model endpoint returns
+`IN_QUEUE` when the key is valid, then fails validation on the missing prompt,
+which costs nothing.
+
+## Everyday 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 remotion render BigBull out/big-bull.mp4 --codec h264
+```
+
+`--context` takes either a file path or the text itself.
+
+## What each step costs
+
+| Step | Time | Notes |
+|---|---|---|
+| draft | 10 to 30s | One OpenAI call. Optional. |
+| voices | about 5s per scene | Sarvam, cheap. |
+| images | 20 to 60s each | The bulk of the cost. 12 images for a 60s story. |
+| render | 2 to 4 min for 60s at 1080p | Local, CPU bound. |
+
+Everything is resumable. `generate` skips any file already on disk, so a failed
+run picks up where it stopped and an edit to one scene only regenerates that
+scene's assets.
+
+## Troubleshooting
+
+**`story.json is invalid`**
+The zod issues are printed with paths. Common causes: a scene image id reused
+across scenes, `stat` present but missing `label`, `slug` containing uppercase
+or spaces.
+
+**`Story "x" has scenes without a durationInFrames`**
+The composition was opened before assets were generated. Run
+`npm run generate -- --slug x`.
+
+**`export 'Logging' was not found in 'mediabunny'`**
+Mixed Remotion versions. `npx remotion versions`, then `npx remotion upgrade`,
+then install the exact list it prints. All `@remotion/*` on one version, and
+`mediabunny` on the version that release expects.
+
+**`The font X does not have a weight 800`**
+That family does not ship the weight. Check with
+`node -e "console.log(Object.keys(require('@remotion/google-fonts/X').getInfo().fonts.normal))"`
+and lower the weight in `src/lib/fonts.ts`.
+
+**Sarvam 400 on a request that used to work**
+`sarvamai` 1.1.5 switched the request keys to snake_case: `language_code`,
+`speech_sample_rate`. `temperature` is bulbul:v3 only; `enable_preprocessing`,
+`pitch` and `loudness` are bulbul:v2 only. `cli/service.ts` already branches on
+the model, so this only bites custom code.
+
+**Subtitles drift from the voice**
+A scene's `durationInFrames` no longer matches its audio. Regenerate that voice
+file, or delete it and rerun `generate` so the duration is measured again.
+
+**Faces look nothing like the reference**
+The scene prompt buried the likeness clause. Put "keep the face, spectacles and
+features clearly recognisable" first, scene direction second. See `images.md`.
+
+**Render is slow or runs out of memory**
+Lower concurrency: `npx remotion render <id> out/x.mp4 --concurrency 4`. For
+very long stories raise the heap:
+`NODE_OPTIONS=--max-old-space-size=8192 npx remotion render ...`.
+
+## Housekeeping
+
+`public/**/*.wav`, `*.mp3`, `*.jpg` and `*.png` are gitignored: `story.json` is
+the artefact worth committing, since it regenerates everything else. Never
+commit `.env`, and never paste a key into `.claude/settings.local.json`
+permission rules, where it would be stored in plain text.