reelkit-cli 0.1.0

package/skill/reference/motion-design.md

@@ -0,0 +1,62 @@
+---
+name: motion-design
+description: Use when deciding how a scene looks and moves - layout, typography, colour, springs, pacing to speech, continuity between scenes, and the rules that stop a video looking AI-generated.
+---
+
+# Motion design guidelines
+
+## The user's uploads
+`assets/index.json` lists the user's own files with a description of each. Show each one only in the scenes whose userAssetKeys include it, sized and framed for what it is: a logo small and clean on a plain area; a screenshot framed in a device or browser mockup (search the library with `reelkit assets search "phone mockup" --kind component`, then `reelkit assets pull <id>`, which puts it in `src/`; if none fits, build a simple rounded framed card); a product photo large, with KenBurnsImage or a rounded card. Never stretch a logo, never crop a screenshot's important part, and never invent a screen when a real one was supplied.
+
+## One system, start to end
+- One base colour, one text colour and **one hero colour**, kept for the whole video. Roughly 60 percent base, 30 percent secondary surfaces, 10 percent hero.
+- The hero colour appears on **at most one element per frame**: it tells the eye where to look. Highlight one word per headline, not the whole line.
+- A soft glow is allowed on the hero element only. More than one glowing element per frame looks cheap.
+- One typeface family, two weights. One icon style with one stroke weight.
+- Carry one visual thread through every scene: the same badge style, accent shape or background treatment. Scenes should feel like one piece transforming, not slides.
+- Where two scenes share an idea, carry an element across: the number becomes the badge, the word stays while its container changes. A shared element beats a fade.
+
+## Layout
+- One focal point per scene. Everything else supports it.
+- Keep important content inside the middle 80 percent of the frame horizontally. On vertical video keep critical text in the middle 75 percent vertically: the platform's own buttons cover the top and bottom. Captions sit just above the bottom of that zone.
+- Reuse the same margins in every scene.
+- Vary composition between scenes (centred, top-aligned, split) so the video is not one slide repeated.
+
+## Typography
+- Headlines 7 to 10 percent of the frame width; supporting text 3.5 to 5 percent. Never smaller than 3 percent: it must read on a phone.
+- If any on-screen text is Hebrew, set it in one of the kit's Hebrew faces and give its container `direction: "rtl"`. The Latin faces have no Hebrew letters. Good pairings: `heebo` or `assistant` for everything; `secularOne` or `karantina` headlines over `assistant` body; `suezOne` or `frankRuhlLibre` for an editorial feel; `varelaRound` or `fredoka` for a friendly one.
+- Short lines, broken by meaning, not by width. A title should fit on one line where it can.
+- Reveal text with a masked rise (translate up from behind an overflow-hidden box), word by word, about 2 frames apart. Avoid plain opacity fades for headlines.
+
+## Motion
+- **Springs, never linear moves and never cartoon bounce.** Use `spring()` with a damping high enough for a tiny overshoot at most. Presets (stiffness / damping): snappy UI 320 / 30, default containers 170 / 26, heavy type and logos 120 / 24.
+- **One thing moves at a time.** Stagger related items by 4 to 8 frames rather than moving everything at once.
+- **Pace to speech.** One visible change per spoken beat, roughly every 0.4 to 1.2 seconds. Use the word timings in `s.words` to bring an element in on the frame its word starts, never before.
+- Something new should happen every 2 to 4 seconds, and something must move within the first half second of the video. No dead stretches.
+- **Rhythm is hit, hold, build.** A fast move, then a hold of about half a second where nothing new enters, then the next move. Constant motion reads amateur; contrast reads expensive. During a hold, settled elements keep their slow breathe.
+- **Nothing sits perfectly frozen for more than about a second.** After an element settles, keep a very slow drift or scale (1 to 2 percent over the scene) alive so the frame breathes.
+- Let an element finish animating and stay readable for at least 1.5 seconds before it leaves.
+- Counters, progress bars and drawn lines finish before the scene's midpoint.
+- Text that swaps inside a container that is also changing size needs its own exit and enter timing, or old and new text overlap.
+
+## Legibility over images and footage
+- Text over an image or footage needs help: a dim layer of 0.2 to 0.45 on the media, or a solid plate behind the text, plus a soft shadow.
+- In footage mode keep overlays to one graphic at a time, clear of the subject.
+
+## Truth on screen
+- Never show a number, quote, price, statistic or result that is not in the narration or on-screen text of the plan.
+- A chart or gauge with no real data behind it uses relative shapes with no figures, or is labelled "Example".
+- Do not invent product screens or features. A recreated interface that is not the user's real one is illustrative and should look generic.
+
+## Determinism
+- Never use `Math.random()` or the clock. A frame must render the same every time. Use `random(seed)` from remotion for any variation.
+- Everything is a function of `useCurrentFrame()`. No CSS transitions or animations, no timers.
+
+## Shape of a 30 second video
+Hook (first 1.5 s: the boldest visual and claim) → context (one line, one visual) → body (three or four beats) → payoff (the result or number, the biggest animation of the video) → close (one action, calm).
+
+## Banned, because they read as AI-made or cheap
+Flat solid backgrounds, opacity-only fades, everything entering at once, rainbow or multi-stop gradients on text and UI, particles and sparkles, glows on interface chrome, emoji as graphics, bouncy easing, gratuitous 3D flips, a centred title on a plain gradient, mixed icon styles, lorem ipsum, and anything that looks like a stock template.
+
+## Check your own frames
+Run `reelkit preview`, then look at the frames in `out/preview/` as a harsh director would. Hunt for: text overlapping during a swap, text cut by the frame edge, type too small for a phone, a frame with nothing in it, and anything that looks like a template. Fix what is real, then check again.

package/skill/reference/remotion-composition.md

@@ -0,0 +1,58 @@
+---
+name: remotion-composition
+description: Use when writing Video.tsx - the file rules, timing model and media rules every composition must follow.
+---
+
+# Writing the composition
+
+## Files
+- `Video.tsx` is required and must contain `export const Video: React.FC<VideoProps> = ({ manifest, urls }) => ...`.
+- Extra component files are flat siblings, PascalCase, one component per file: `NumberBadge.tsx` exports `NumberBadge`. Import them in Video.tsx as `./NumberBadge`.
+- Video.tsx may import only `react`, `remotion`, `reelkit/kit` and sibling components. No other packages, no network, no file access, no `process`.
+
+## Timing
+- All timing comes from the manifest. Each scene has `startFrame` and `durationFrames`; wrap each scene's content in `<SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>`.
+- Inside a SceneFrame, `useCurrentFrame()` starts at 0 for that scene.
+- Never hard-code a duration that the manifest already gives. Look scenes up by id when a scene needs bespoke content.
+
+## Media
+- Reference media only as `urls[path]`, where `path` is the file's project path, using the paths in the manifest: `s.voiceoverKey`, `s.imageKey`, `s.userAssetKeys`, `manifest.footageKey`. Never hard-code a URL.
+- A scene with narration has `s.voiceoverKey`: give it exactly one `<Voiceover src={urls[s.voiceoverKey]} />` inside its SceneFrame, and `<Captions words={s.words} />` unless the notes say otherwise.
+- Footage mode (`manifest.footageKey` is set): one `<FootageLayer>` at the bottom, outside the scenes.
+- User images: `<Img src={urls[key]} />` from remotion.
+
+## Layer stack (every video, bottom to top)
+1. Background: `<BgMesh>` from the kit, or `<FootageLayer>` in footage mode. Never a flat solid colour.
+2. Images: `<KenBurnsImage>` inside its scene. Every still image moves; alternate `direction` between consecutive image scenes.
+3. Graphics and type, inside each scene's SceneFrame.
+4. `<Grade>`, then `<Grain>`, then `<Vignette>`, once, at the very top of the video outside the scenes. In footage mode skip Grade.
+
+## Shared overlays (optional)
+- The library has ready-made overlay clips (`reelkit assets search "<description>" --kind overlay`): film marks, HUD frames, corner marks. They are white on black and are laid over the video with `<ScreenOverlay>`.
+- Most videos need none. Use one only when the topic or look calls for it (film, tech, editorial), on a dark theme, at low opacity (0.3 to 0.6).
+- At most one overlay per video, placed above the scenes and below Grade, kept clear of captions and headlines.
+- Only use kind "frame". Kind "badge" overlays are labels and ratings (4K, HDR, age ratings, "Coming Soon", "Directed by"): they make a claim about the video, so use one only if the narration literally says it.
+- Run `reelkit assets pull <id>` before referencing an overlay. It lands in `assets/lib/<id>/`; reference it as `urls["assets/lib/<id>/<file>"]`, and read its duration from `assets/library.json`.
+
+## Animation rules
+- **No linear motion.** Every `interpolate()` takes an `easing` from the kit's `ease` and both `extrapolateLeft: "clamp"` and `extrapolateRight: "clamp"`. Entrances use `spring()` with a kit `springs` preset.
+- **Entrances move two or three properties together** (opacity, position, scale). Wrap content in `<Entrance>` rather than fading alone.
+- **Stagger, never simultaneous.** Words 3 frames apart, list items and cards 4 to 5, big blocks 6.
+- **Exits exist and are faster than entrances** (about 10 frames against 20). Use `<Entrance exitAt={...}>` or the SceneFrame fade.
+- **A missing clamp shows elements before their entrance or after their exit.** Check for it.
+- Derive timing from `fps` in `useVideoConfig()`, not bare frame counts, when you express a duration in seconds.
+
+## Theme
+- Declare one palette object at the top of Video.tsx (a kit `palettes` entry or your own `Palette`) and take every colour from it. No stray hex values inside components; components receive colours as props.
+- Use `fonts.display` at weight 600 to 800 for headlines and numbers and `fonts.body` for supporting text.
+- Use pixel values, not `em`, for gaps and margins around large type: `em` resolves against the parent's font size and collapses next to big text.
+- No emoji as icons. They ignore the palette. For a platform logo use the kit's `<Icon name="instagram" ... />`; never draw a logo yourself or stand a letter in for it. For anything else draw a simple glyph with SVG in palette colours, or use one of the Icon glyphs.
+
+## Content
+- The plan is not available at render time. Bake each scene's on-screen text and direction into the code.
+- Size everything relative to `useVideoConfig()` width and height, never fixed pixels, so it works at any aspect.
+
+## Workflow
+1. `reelkit assets search "<description>" --kind component`, and `reelkit assets pull <id>` for any you plan to use (it lands in `src/`).
+2. Write each new component in `src/`, then `src/Video.tsx`.
+3. `reelkit check`. Fix every error it reports and check again until it passes.

package/skill/reference/scene-treatments.md

@@ -0,0 +1,35 @@
+---
+name: scene-treatments
+description: Use when choosing each scene's visual treatment and writing image prompts, shareable flags and direction notes.
+---
+
+# Choosing scene treatments
+
+## The three treatments
+- **motion-graphic** - animated text, numbers, shapes and icons drawn in code. The default. Best for hooks, lists, statistics, steps and calls to action.
+- **illustration** - one generated picture behind the text. Use when a concrete image carries the point better than type (an object, a place, a mood). At most half the scenes; each one costs money.
+- **footage-overlay** - text and graphics over the user's own video. Required for every scene when footage was supplied, and never used otherwise.
+
+## Image prompts (illustration scenes only)
+- Describe subject, setting, style and mood in one or two sentences. Keep one consistent style across the video.
+- Never ask for text, letters, logos or UI inside the picture.
+- Leave clear space where on-screen text will sit.
+- Before writing a new prompt, run `reelkit assets search "<description>" --kind image`: if a suitable shared image exists, word the prompt to match it so you can reuse it.
+
+## shareable and imageTags
+- shareable is true only when the picture is generic stock-style imagery any other video could use. Write shareable prompts in generic terms.
+- shareable is false when the prompt depends on the user's brand, product, name, place or uploads, and whenever imagePrompt is null.
+- imageTags: 3 to 6 short lowercase tags (subject, style, mood). Empty when imagePrompt is null.
+
+## User assets
+- Only reference assets listed in `assets/index.json`, by id, in userAssetIds.
+- Put a logo in the first or last scene. Put a screenshot in the scene that talks about what it shows.
+
+## One idea, one look
+- One idea per scene, and one visual per idea. If a scene needs two visuals, it is two scenes.
+- Describe the real object the narration is about (the phone, the receipt, the glass, the chart), not an abstract shape.
+- Plan a visual thread that runs through every scene, and say what it is in the first scene's notes.
+
+## Notes for the composition
+- One or two sentences per scene: layout, what animates, emphasis, colour mood.
+- Name library components found with `reelkit assets search "<description>" --kind component` when one fits.

package/skill/reference/scriptwriting.md

@@ -0,0 +1,44 @@
+---
+name: scriptwriting
+description: Use when writing the spoken script for a short social video - hooks, pacing, structure and length.
+---
+
+# Scriptwriting for short video
+
+## Length and pace
+- Narration is spoken at about 2.5 words per second. A 30 second video is about 75 words; 60 seconds is about 150.
+- Without footage, aim for 30 to 60 seconds in total. With footage, never exceed the word limit that `reelkit plan check` reports.
+- One idea per scene. A scene is one or two sentences, 8 to 30 words.
+
+## Structure
+1. **Hook (scene 1):** a question, a surprising claim or a named pain. No greetings, no "in this video".
+2. **Body (1 to 6 scenes):** one point per scene, in an order that builds. Number the points when the idea is a list.
+3. **Takeaway (last scene):** one concrete action or line to remember.
+
+## Voice
+- Write for the ear: short sentences, contractions, plain words. Read it aloud in your head.
+- Write numbers as they are spoken ("seventy-five percent"), since the text goes to a voice model.
+- No emoji, no hashtags, no stage directions in narration.
+- Write in the language of the idea. If the idea is in Hebrew, write the script in Hebrew.
+
+## Using the user's uploads
+Each of the user's files in `assets/index.json` has a description of what it shows. Use an asset in the scene where it is relevant to what is being said, and leave out any that fit nowhere: a logo in the opening or closing scene, a screenshot where the narration talks about that screen, a product photo where the product is named. Put its id in that scene's userAssetIds and say in the notes how to show it.
+
+## Choosing the voice
+`reelkit assets voices` lists the available voices with a description, gender, accent and language (`--json` also gives each voice's kind). Pick one `voiceId` for the whole video and a `pace`.
+
+- **Language first.** For Hebrew narration choose a voice whose language is Hebrew if there is one. For English, choose an accent that suits the audience; default to a neutral one.
+- **Match the energy of the idea.** Punchy tips, lists and promos: an energetic, social-media style voice. Explainers and how-tos: a clear, friendly educator. Finance, health, legal and B2B: a steady, trustworthy voice. Stories and reflective pieces: a warm storyteller.
+- **Match the speaker the script implies.** If the script speaks as the brand or founder ("we build..."), prefer the owner's own cloned voice when one is listed (kind "cloned"). Otherwise choose freely; do not pick a gender by stereotype of the topic.
+- **Avoid character voices** (described as a villain, warrior, trickster, cartoon or similar) unless the idea is playful and calls for one.
+- **Pace:** "normal" by default, "fast" for high-energy hooks and lists, "slow" for calm, emotional or complex material. A fast pace fits more words per second; keep the word limit either way.
+- Vary your choice across videos: do not default to the first voice in the list.
+
+## Truthfulness
+- Never invent numbers, statistics, quotes, prices, testimonials or results. Use a figure only when the idea supplies it or it is common knowledge you are sure of; otherwise make the point without a number.
+- Do not claim features or facts about the user's product that the idea did not state.
+- No fake urgency or made-up social proof.
+
+## On-screen text
+- onScreenText is what appears on screen, not the narration. Two to five words per item, at most three items per scene.
+- It should reinforce the spoken point (a keyword, a number, a label), never repeat the sentence.

package/skill/reference/sound-design.md

@@ -0,0 +1,43 @@
+---
+name: sound-design
+description: Use when adding sound effects to a video - which moments get a sound, how to search the shared sound library, timing against the visual, and volume under the voiceover.
+---
+
+# Sound design
+
+A few well-placed sounds make motion feel real. Too many make a video tiring. The voiceover is always the most important sound.
+
+## What gets a sound
+- **Entrances that matter:** the hook's first hit, each numbered point arriving, the payoff. A whoosh, swipe or soft impact.
+- **Scene changes:** a short transition sound across the cut.
+- **Interface moments:** a notification arriving, a button tap, a tick appearing. A click, pop or chime.
+- **Build-ups:** a riser into the payoff or the final call to action.
+- Not every element. Two to four sounds per scene at most, and usually one.
+
+## Finding sounds
+1. `reelkit assets search "<description>" --kind sfx` with what you want to hear: "whoosh", "soft click", "notification pop", "riser", "camera shutter", "bass impact". Add "one-shot" or "short" to the query for one-shots.
+2. Prefer short sounds (under two seconds) for motion. Use longer ones for risers and long transitions. Use an ambience or drone bed only when the video has no other background and the mood calls for it, at very low volume.
+3. `reelkit assets pull <id>` with the id you picked. It lands in `assets/lib/<id>/` and the command prints the `urls[...]` path to use; place it with `<Sfx>`.
+4. Reuse one whoosh and one click across the video rather than a different sound each time. Consistency sounds designed.
+
+## Timing
+- Start a whoosh or swipe **2 to 3 frames before** the visual lands. Early feels in sync; late feels broken.
+- Put impacts and clicks on the exact frame the visual hits.
+- Start a riser so that it **ends** on the reveal: `at = revealFrame - durationSec * fps`.
+- Use the word timings in `s.words` when a sound belongs to a spoken word.
+
+## Volume
+- The voiceover plays at 1. Sound effects sit between 0.2 and 0.45. Impacts on the hook can go to 0.6.
+- Ambience and drone beds: 0.06 to 0.12.
+- Never let two loud sounds overlap. Stagger them.
+
+## Fit
+- Match the sound to the look: soft pops and gentle whooshes for calm, friendly videos; glitches and bass hits for tech and high energy; camera and tape sounds for retro.
+- Skip anything startling (gunshots, screams, alarms) unless the topic is literally about it.
+- Do not use a sound that names a brand or device the video is not about.
+
+## Placing
+```tsx
+<Sfx src={urls["assets/lib/<id>/clip.mp3"]} at={12} volume={0.35} />
+```
+Inside a SceneFrame, `at` counts from the start of that scene.

package/src/agents.ts

@@ -0,0 +1,103 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import type { Ctx } from "./context";
+import { PKG_ROOT } from "./render/validate";
+
+type Env = Record<string, string | undefined>;
+
+// Every path is relative to the agents home. Skill folders: the vercel-labs/skills README. Command folders: each agent's own docs.
+export const AGENTS: { id: string; name: string; home: string; skillDir: string; commandFile?: string }[] = [
+  { id: "claude", name: "Claude Code", home: ".claude", skillDir: ".claude/skills/reelkit", commandFile: ".claude/commands/reelkit-video.md" },
+  { id: "codex", name: "Codex", home: ".codex", skillDir: ".codex/skills/reelkit", commandFile: ".codex/prompts/reelkit-video.md" },
+  { id: "cursor", name: "Cursor", home: ".cursor", skillDir: ".cursor/skills/reelkit" },
+  { id: "gemini", name: "Gemini CLI", home: ".gemini", skillDir: ".gemini/skills/reelkit" },
+  { id: "agents", name: "Shared agents folder", home: ".agents", skillDir: ".agents/skills/reelkit" },
+];
+
+// The only place the home directory is read. Tests and smoke runs point REELKIT_AGENTS_HOME at a temp folder.
+export const agentsHome = (env: Env): string => env.REELKIT_AGENTS_HOME || homedir();
+
+const SKILL_SRC = join(PKG_ROOT, "skill");
+const VERSION_FILE = ".reelkit-version";
+const packageVersion = (): string => JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version;
+
+// A killed run can leave staged or backup folders. Put back the newest backup if the install itself is gone, then clear the rest.
+function recoverLeftovers(dest: string): void {
+  const parent = dirname(dest);
+  if (!existsSync(parent)) return;
+  const left = readdirSync(parent).filter((n) => /^\.reelkit\.(tmp|old)-/.test(n)).map((n) => join(parent, n));
+  const olds = left.filter((p) => basename(p).startsWith(".reelkit.old-")).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+  if (!existsSync(dest) && olds[0]) renameSync(olds[0], dest);
+  for (const p of left) rmSync(p, { recursive: true, force: true });
+}
+
+export type InstallReport = { installed: { agent: string; path: string }[]; skipped: { agent: string; reason: string }[] };
+
+export function installSkill(env: Env, opts: { agents?: string[]; force?: boolean; source?: string; rename?: (from: string, to: string) => void }): InstallReport {
+  const source = opts.source ?? SKILL_SRC;
+  if (!existsSync(join(source, "SKILL.md")) || !existsSync(join(source, "command.md"))) {
+    throw new Error("Reelkit's skill files are missing from this installation. Reinstall reelkit and try again.");
+  }
+  const rename = opts.rename ?? renameSync;
+  const home = agentsHome(env);
+  const version = packageVersion();
+  const report: InstallReport = { installed: [], skipped: [] };
+  const named = opts.agents !== undefined;
+  for (const agent of AGENTS.filter((a) => !named || opts.agents!.includes(a.id))) {
+    if (!named && !existsSync(join(home, agent.home))) {
+      report.skipped.push({ agent: agent.id, reason: "not installed on this machine" });
+      continue;
+    }
+    const dest = join(home, agent.skillDir);
+    recoverLeftovers(dest);
+    const current = existsSync(join(dest, VERSION_FILE)) ? readFileSync(join(dest, VERSION_FILE), "utf8").trim() : undefined;
+    const commandPath = agent.commandFile && join(home, agent.commandFile);
+    if (!opts.force && current === version && (!commandPath || existsSync(commandPath))) {
+      report.skipped.push({ agent: agent.id, reason: "already up to date" });
+      continue;
+    }
+    // Stage next to the destination, then swap by renames only, so no step deletes the old install before the new one is in place.
+    const staged = join(dirname(dest), `.reelkit.tmp-${process.pid}`);
+    const backup = join(dirname(dest), `.reelkit.old-${process.pid}`);
+    try {
+      mkdirSync(dirname(dest), { recursive: true });
+      cpSync(source, staged, { recursive: true, filter: (src) => src !== join(source, "command.md") });
+      writeFileSync(join(staged, VERSION_FILE), `${version}\n`);
+      const hadOld = existsSync(dest);
+      if (hadOld) rename(dest, backup);
+      try {
+        rename(staged, dest);
+      } catch (e) {
+        if (hadOld) rename(backup, dest);
+        throw e;
+      }
+    } finally {
+      rmSync(staged, { recursive: true, force: true });
+      if (existsSync(dest)) rmSync(backup, { recursive: true, force: true }); // never delete the backup while nothing is in place
+    }
+    if (commandPath) {
+      mkdirSync(dirname(commandPath), { recursive: true });
+      cpSync(join(source, "command.md"), commandPath);
+    }
+    report.installed.push({ agent: agent.id, path: dest });
+  }
+  return report;
+}
+
+// The quiet form that rides on init and auth login: detected agents only, never fails, silent when current.
+export function ensureSkill(ctx: Ctx): void {
+  if (ctx.env.REELKIT_NO_AUTO_INSTALL === "1") return;
+  try {
+    const home = agentsHome(ctx.env);
+    for (const agent of AGENTS.filter((a) => existsSync(join(home, a.home)))) {
+      try {
+        if (installSkill(ctx.env, { agents: [agent.id] }).installed.length) ctx.log(`Installed the Reelkit skill for ${agent.name}`);
+      } catch (e) {
+        ctx.log(`Could not install the Reelkit skill for ${agent.name}: ${(e instanceof Error ? e.message : String(e)).split("\n")[0]}`);
+      }
+    }
+  } catch (e) {
+    ctx.log(`Could not install the Reelkit skill: ${(e instanceof Error ? e.message : String(e)).split("\n")[0]}`);
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { z } from "zod";
+import { ApiErrorSchema, ErrorCodeSchema, routes, type ErrorCode, type RouteName, type Routes } from "../contract";
+
+export class ApiFailure extends Error {
+  constructor(public code: ErrorCode, message: string) { super(message); }
+}
+
+const VERSION = (JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version: string }).version;
+
+export type Api = <K extends RouteName>(name: K, input: z.input<Routes[K]["req"]>) => Promise<z.infer<Routes[K]["res"]>>;
+
+export function createClient(opts: { baseUrl: string; token?: string }): Api {
+  return async (name, input) => {
+    const r = routes[name];
+    if (r.auth && !opts.token) throw new ApiFailure("unauthenticated", "Not logged in. Run `reelkit auth login`.");
+    const url = new URL(opts.baseUrl.replace(/\/$/, "") + r.path);
+    const headers: Record<string, string> = { "user-agent": `reelkit/${VERSION}` };
+    if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+    let body: string | undefined;
+    if (r.method === "GET") {
+      for (const [k, v] of Object.entries(input as Record<string, unknown>)) if (v !== undefined) url.searchParams.set(k, String(v));
+    } else {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(input);
+    }
+    let res: Response;
+    try {
+      res = await fetch(url, { method: r.method, headers, body });
+    } catch {
+      throw new ApiFailure("server_error", `Cannot reach the Reelkit API at ${opts.baseUrl}. Check your connection or REELKIT_API_URL.`);
+    }
+    const json: unknown = await res.json().catch(() => undefined);
+    if (!res.ok) {
+      const err = ApiErrorSchema.safeParse(json);
+      // A code this version does not know is a server_error, but the server's own message is kept.
+      const known = err.success ? ErrorCodeSchema.safeParse(err.data.error.code) : undefined;
+      throw err.success ? new ApiFailure(known?.success ? known.data : "server_error", err.data.error.message) : new ApiFailure("server_error", `The Reelkit API returned ${res.status}.`);
+    }
+    const parsed = r.res.safeParse(json);
+    if (!parsed.success) throw new ApiFailure("server_error", "The Reelkit API sent a response this version of reelkit does not understand. Update reelkit and try again.");
+    return parsed.data as never;
+  };
+}
+
+export async function download(url: string, destPath: string): Promise<void> {
+  const res = await fetch(url);
+  if (!res.ok) throw new ApiFailure("server_error", `Download failed with ${res.status}. Run the command again.`);
+  await mkdir(dirname(destPath), { recursive: true });
+  await writeFile(destPath, new Uint8Array(await res.arrayBuffer()));
+}
+
+export async function uploadTo(url: string, bytes: Uint8Array, contentType: string): Promise<void> {
+  const res = await fetch(url, { method: "PUT", headers: { "content-type": contentType }, body: bytes as BodyInit });
+  if (!res.ok) throw new ApiFailure("server_error", `Upload failed with ${res.status}. Run the command again.`);
+}

package/src/cli.ts

@@ -0,0 +1,91 @@
+import { Command } from "commander";
+import { ApiFailure } from "./api/client";
+import { assetsGenImage, assetsPull, assetsSearch, assetsUpload, assetsVoiceover, assetsVoices } from "./commands/assets";
+import { authLogin, authLogout, whoami } from "./commands/auth";
+import { check, preview, render } from "./commands/build";
+import { init } from "./commands/init";
+import { install } from "./commands/install";
+import { openInBrowser } from "./open";
+import { planCheck } from "./commands/plan";
+import type { Ctx, Result } from "./context";
+
+const ctx: Ctx = {
+  cwd: process.cwd(),
+  env: process.env,
+  log: (line) => console.error(line),
+  sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+  // Read when used, not when this module loads.
+  get isTTY() { return Boolean(process.stdout.isTTY); },
+  openUrl: openInBrowser,
+};
+
+// "reelkit assets pull" from the Command object commander passes as the last action argument.
+export function titleOf(args: unknown[]): string {
+  const names: string[] = [];
+  const last = args.at(-1);
+  for (let c = last instanceof Command ? last : undefined; c?.parent; c = c.parent) names.unshift(c.name());
+  return `reelkit ${names.join(" ")}`.trim();
+}
+
+// Runs a command, prints its result, and sets the exit code. Progress goes to stderr so --json output stays clean.
+export function run<A extends unknown[]>(fn: (ctx: Ctx, ...args: A) => Promise<Result>) {
+  return async (...args: A) => {
+    const json = program.opts().json as boolean | undefined;
+    if (process.stdout.isTTY && !json) {
+      // Loaded only when a person is watching, so scripted runs never pay for it.
+      const { runInk } = await import("./ui/run");
+      const res = await runInk(titleOf(args), (log) => fn({ ...ctx, log }, ...args));
+      if (!res.ok) process.exitCode = 1;
+      return;
+    }
+    try {
+      const res = await fn(ctx, ...args);
+      console.log(json ? JSON.stringify({ ok: res.ok, summary: res.summary, data: res.data ?? null }, null, 2) : res.summary);
+      if (!res.ok) process.exitCode = 1;
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      const code = e instanceof ApiFailure ? e.code : "error";
+      if (json) console.log(JSON.stringify({ ok: false, summary: message, data: { code } }, null, 2));
+      else console.error(message);
+      process.exitCode = 1;
+    }
+  };
+}
+
+export const program = new Command().name("reelkit").description("Make short-form video with a shared asset library.").option("--json", "print the result as JSON");
+
+const auth = program.command("auth").description("Log in and out");
+auth.command("login").description("Log in to Reelkit: opens the login page in your browser").option("--start", "begin a login and return the link at once, without opening a browser (for an agent)").option("--finish", "finish a login begun with --start")
+  .option("--no-browser", "print the link but do not open it (also: REELKIT_NO_BROWSER=1)")
+  .action(run((ctx, opts) => authLogin(ctx, { ...opts, json: Boolean(program.opts().json) })));
+auth.command("logout").description("Log out and remove the stored token").action(run(authLogout));
+program.command("whoami").description("Show your account, quota and contributions").action(run(whoami));
+
+program.command("init [name]").description("Set up a video project (in a new folder named after it, or in this folder)").option("--aspect <aspect>", "9:16, 16:9 or 1:1").action(run(init));
+
+const assets = program.command("assets").description("Find, add and generate the files a video needs");
+assets.command("upload <file>").description("Add one of your own files to this project (private unless --share)")
+  .option("--describe <text>", "what the file shows").option("--footage", "use this video as the footage to overlay")
+  .option("--share", "also send it to the shared library").option("--kind <kind>", "library kind when sharing").option("--tags <tags>", "comma-separated tags when sharing")
+  .action(run(assetsUpload));
+assets.command("search <query>").description("Search the shared library by meaning; each result shows how well it fits").option("--kind <kind>", "image, overlay, sfx, music, component or clip").option("--limit <n>", "how many results")
+  .action(run(assetsSearch));
+assets.command("pull <id>").description("Download a library item into this project").option("--scene <sceneId>", "use it as this scene's image").option("--force", "replace a component file that already exists")
+  .action(run(assetsPull));
+assets.command("voices").description("List the narration voices").action(run(assetsVoices));
+assets.command("voiceover").description("Record the narration from plan.json").option("--scene <sceneId>", "one scene").option("--all", "every scene").option("--redo", "record again even if it exists")
+  .action(run(assetsVoiceover));
+assets.command("gen").description("Generate an asset").command("image [prompt]").description("Generate a scene's illustration; the prompt defaults to the plan's")
+  .requiredOption("--scene <sceneId>", "the scene it is for").option("--redo", "generate a new image even if the scene has one").action(run(assetsGenImage));
+
+program.command("plan").description("Work with plan.json").command("check").description("Validate plan.json and list what to fix or improve").action(run(planCheck));
+
+program.command("check").description("Check the composition in src/ without rendering").action(run(check));
+program.command("install").description("Install the Reelkit skill into your coding agents").option("--agent <id>", "claude, codex, cursor, gemini, agents or all").option("--force", "reinstall even when up to date").action(run((ctx, opts) => install(ctx, opts)));
+program.command("preview").description("Render one test frame per scene into out/preview/").action(run((ctx) => preview(ctx)));
+program.command("render").description("Render the video to out/video.mp4").action(run(render));
+
+// Parses argv and runs the chosen command. Importing this module parses nothing; bin/reelkit.mjs calls main.
+export async function main(argv: string[]): Promise<void> {
+  await program.parseAsync(argv).catch((e) => { console.error(e instanceof Error ? e.message : String(e)); process.exitCode = 1; });
+}