AGENTS.md

Instructions for any AI coding agent working in this repository — Codex CLI, Cursor, Gemini CLI, opencode, GitHub Copilot, Windsurf, Aider, Claude Code, or whatever comes next. This file is the AGENTS.md open standard; Claude Code reads the same content through skills/.

No agent is required to use this kit. Every script runs on its own from a terminal — see docs/NO-AGENT.md.

START HERE — install, then open the studio

If the person has just pointed you at this repository, or asks you to install it, set it up, or get it running: run this first, before reading anything else. It is the whole setup.

python install.py --yes

(python3 install.py --yes if python is not on the PATH. On Windows, py install.py --yes.)

It installs Node, FFmpeg and the Python packages, scaffolds a project in my-video/, and opens the Remotion studio — the live preview — in the browser, then exits. The studio keeps running after the command finishes; that is deliberate, so you are not left holding an open process.

The studio opening is the point. It is how the person sees that it worked. Do not skip it, and do not replace it with npm run dev in the foreground — that blocks your turn and they see nothing.

Tell them the URL it printed (http://localhost:3000, or the next free port). If their browser did not open by itself, that address is what they paste into it.

If the studio needs opening again later

python skills/vertical-video/scripts/studio.py my-video

Same thing: detached, waits until it is really answering, opens a browser, exits. Inside a project, npm run dev does it in the foreground instead.

If install.py stops with something missing

It could not install Node or FFmpeg itself — no package manager, or no permission. It prints exactly what is missing. Give the person the matching commands from docs/NO-AGENT.md for their platform, then run python install.py --yes again. On Windows, Node and FFmpeg only land on the PATH in a new terminal.

What not to do here

• Don't commit the project folder install.py creates. It is the person's work, not part of the kit.
• Don't run the studio in the foreground as your own command; it never returns.
• Don't wait for a render to check a layout. Use a still — see below.

Company context lives in private/, never in the repo

This repository is public. A company's brand brief, approved scripts, voices, internal decisions, people's names and numbers belong in private/ at the kit root. It is gitignored, so it stays on this machine.

• Before building anything, read every file in private/ if the folder exists. That is where the person's earlier work and decisions are — what they approved, what they rejected, exact colours and fonts, prompts that worked. Apply it; don't re-ask what it already answers.
• Never copy from it into a tracked file, a commit message, a pull request or an issue: not a name, a phone number, an email address, an unpublished figure, not even the company's name as an example. Anything generic the kit should learn goes into the kit in generic words.
• Projects created inside the kit are ignored too: new_project.py writes a * .gitignore into each one, whatever its name. Don't delete it.
• If the person asks you to push something that came from private/, tell them the repository is public and let them decide.

What this repo is

A kit for making 9:16 short-form video (TikTok, Reels, Shorts) in code: AI narration, word-by-word captions, and a real 1080×1920 Remotion render.

The one idea everything follows from: content lives apart from design. Changing a line of narration is editing one line and re-running a script — not re-recording and re-cutting.

Read these before you act

Those files are the real instructions. This one is the index.

The flow, in one screen

python install.py --yes        # once: dependencies, a project, the studio open

cd my-video
python scripts/brand.py --compare   # after asking about the brand: style, logo, colors
# edit script.json (what is SAID) and src/content.ts (what is SEEN)
python scripts/voice.py        # narration -> audio/ + src/timings.json
python scripts/captions.py     # word-by-word -> src/captions.json
npm run check                  # does it compile
npm run render                 # output/video.mp4
python scripts/publish.py      # upload/video.mp4, platform-ready
python scripts/share.py        # output/video_light.mp4, for email/WhatsApp

The studio reloads by itself on every save, so leave it open while you work — the person watches the video change as you edit. python scripts/doctor.py reports on the machine if something later looks wrong.

The studio opens on a brand-new project, before any audio exists: scenes fall back to 3 seconds each until voice.py has measured the real narration.

Rules that are not negotiable

Never invent facts. Percentages, prices, dates, claims about what a product does, client names. A plausible number typed in to fill a line becomes a promise the person publishing it never made. Ask for the number, or stay at the level of generality you were actually given — and say what you left pending when you hand the video over, instead of burying it in a code comment.

Content and design stay separate. script.json and src/content.ts are the only files content touches. If a text change requires editing a component, the change is going the wrong way.

Ask about the look before building. A new project starts in the kit's placeholder style. Ask about brand guidelines or a design system, logo, colors, font and feel first, and apply them with scripts/brand.py — see skills/vertical-video/references/style.md. Never ship the default look by accident, and never invent brand colors.

Audio drives timing. Never hardcode a scene duration. voice.py measures the narration and writes src/timings.json; the components read it.

Nothing readable goes in the bottom ~380px or the right ~160px. That is where TikTok and Reels draw their own interface. Set SHOW_SAFE_AREAS = true in src/theme.ts and look before you claim a layout is fine.

Check with single frames, not full renders. A render takes minutes, a frame takes seconds:

npx remotion still src/index.ts Short preview/f.png --frame=90

Look at one frame of each scene type, not just the first.

Don't commit generated media. audio/, output/, upload/, public/audio/ and node_modules/ are gitignored on purpose. They regenerate.

One Remotion for every project. Projects created inside the kit use the node_modules at the kit root — Node looks upward for packages. Don't run npm install inside a project there; new_project.py and studio.py install the shared one when it is missing. Upgrading Remotion means changing both package.json (root and template) together; deps.py checks they match.

Who you are usually helping

Often someone in marketing or communications, frequently non-technical. They do not care what Node or React is, and they should not have to.

Handle the technical side yourself. Talk about what they care about: the hook, the script, how long it runs, how it looks on a phone. Never ask them to edit code — ask for the words and put them where they go.

If they write to you in Spanish, answer in Spanish. The repo ships README.es.md, docs/SIN-AGENTE.md and docs/PROMPTS.es.md for exactly that.

Verifying a change to the kit itself

npm ci                                    # once, at the kit root: shared by every project
python skills/vertical-video/scripts/deps.py   # the root and template versions still match
cd template/remotion-vertical
npm run check
python scripts/voice.py --engine edge --voice en-US-AndrewNeural
python scripts/captions.py
npx remotion still src/index.ts Short preview/f.png --frame=60

Type checking does not catch a layout that renders text under the platform UI. Look at the frame.