@autoaiai/aicut 0.0.0-stage → 0.1.7

package/bin/aicut.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+
+const USAGE = `aicut — a film is a function of time: given t, it draws that moment
+
+  aicut open   [folder | url]      start or open a project; Studio shows it to the person
+  aicut look   [what] [t | a-b]    check the film and draw it: a contact sheet with its sound and loudness
+  aicut render [a-b]               the MP4, saved beside film.html
+  aicut get    [what] [--options]  voice-over, music, sound effects, transcripts, images, video, from a connected service
+
+  Run with no arguments for the manual; \`aicut <command> --help\` for one command's options; --version for the version.
+  look, render and get work on the project around the current folder.
+  Exit status: 0 done, 1 the film or the command failed (the output says why), 2 not a project or a wrong command.`;
+
+/* one command's help: what it does, what it takes, where its output goes */
+const COMMAND_HELP = {
+  open: `aicut open [folder | url]
+
+  folder   a new film: a folder named after it (made if missing); or an existing project
+           A folder that is not a project yet gets an empty film.html, 1920 × 1080 (its viewport <meta>) with no
+           tracks; nothing else is created. Not a code project
+           (package.json, Cargo.toml, go.mod, pyproject.toml…): the film gets a folder of its own inside it.
+  url      a film on GitHub or GitLab: a repository (https://github.com/owner/repo) or a folder in one
+           (…/tree/main/<folder>), copied into the projects library without its git history, then opened
+  without  the project around the current folder, else the one opened last, else Studio's projects (where the
+           person can start one). The current folder is never made a project: name it (.) for that.
+
+  Starts AICUT Studio if it is not running and prints its address. A Studio page already open, in any browser,
+  switches to the project, and nothing more opens; otherwise open the address in your built-in browser, and if no
+  page connects within 15 s, Studio opens the person's browser (AICUT_NO_BROWSER=1: never).`,
+  look: `aicut look [what] [t | a-b]
+
+  what   the project (default), a web page (.html), or a media file (video, image, sound)
+  t      one frame at full size, e.g. 4.5
+  a-b    a dense sheet of a stretch, e.g. 3-6
+         without either: a contact sheet of the whole thing, its sound and loudness, and a check that
+         the same t draws the same picture
+
+  Writes PNGs under .film/cache/look/ of the project and prints their paths. A project Studio has not shown yet is
+  opened in Studio first, so the person watches it.
+
+  --count <n>     frames in a sheet (12)`,
+  render: `aicut render [a-b]
+
+  Render the project around the current folder to video.
+  The whole film goes to <project>/<folder name>.mp4, beside film.html; a range (a-b) goes to .film/cache/render/.
+  A project Studio has not shown yet is opened in Studio first.
+
+  --out <file>    another path; .webm or .mov with --alpha
+  --fps <n>       frame rate (30)
+  --4k            3840 px wide              --scale <n>     any device pixel ratio
+  --blur          motion blur (8 samples)   --samples <n>   --shutter <0..1>
+  --alpha         transparent background    --workers <n>   parallel browsers`,
+};
+
+/* `aicut` alone: the manual, the whole of what an agent needs to know. `get` takes any options its verb has,
+   so it goes to Studio (studio/client.mjs) before the fixed options below are parsed. */
+const RAW = process.argv.slice(2);
+/* the command as the agent can type it here: the one that ran it when it says so (AICUT_RUN: the development
+   checkout's .dev/bin/aicut), through npx always the newest (npx keeps the first one it fetched for a bare name),
+   else `aicut` where it is installed */
+const RUN = process.env.AICUT_RUN || (process.env.npm_command === 'exec' ? 'npx -y @autoaiai/aicut@latest' : 'aicut');
+/**
+ * A newer aicut, said once in a line before what the command prints: looked up on npm (at most daily, briefly) when
+ * a session starts (the manual, open), else only as learnt before, so look, render and get never wait for it.
+ */
+const updateNotice = async (network) => {
+  const latest = await (await import('../studio/client.mjs')).newerAicut({ network }).catch(() => null);
+  if (latest) console.error(`aicut ${latest} is out (this is an older one): run commands as \`npx -y @autoaiai/aicut@latest …\` to use it; it updates Studio too.`);
+};
+if (RAW.length === 0) {
+  const { readFileSync } = await import('node:fs');
+  await updateNotice(true);
+  console.log(readFileSync(new URL('../MANUAL.md', import.meta.url), 'utf8').replaceAll('npx @autoaiai/aicut', RUN));
+  process.exit(0);
+}
+if (RAW.length === 1 && (RAW[0] === '--version' || RAW[0] === '-v')) {
+  const { readFileSync } = await import('node:fs');
+  console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+  process.exit(0);
+}
+await updateNotice(RAW[0] === 'open');
+if (RAW[0] === 'get') {
+  let result;
+  try { result = await (await import('../studio/client.mjs')).getMedia(RAW.slice(1), (line) => console.error(line)); }
+  catch (e) { result = { code: 1, lines: [`aicut get: ${e.message}`] }; }
+  for (const line of result.lines) console.log(line);
+  process.exit(result.code);
+}
+
+/* the help speaks the name this was run as: `aicut` or `npx @autoaiai/aicut` */
+const named = (text) => text.replace(/^( {2})?aicut(?= )/gm, `$1${RUN}`).replace('`aicut <command>', `\`${RUN} <command>`);
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      count: { type: 'string' }, out: { type: 'string', short: 'o' }, '4k': { type: 'boolean' }, scale: { type: 'string' },
+      blur: { type: 'boolean' }, samples: { type: 'string' }, shutter: { type: 'string' }, alpha: { type: 'boolean' },
+      fps: { type: 'string' }, workers: { type: 'string' }, help: { type: 'boolean', short: 'h' },
+    },
+  });
+} catch (e) {
+  /* an option no command has: say which, and what there is, rather than Node's stack */
+  console.error(`${RUN}: ${e.message.replace(/\. To specify a positional argument.*$/s, '')}\n\n${named(USAGE)}`);
+  process.exit(2);
+}
+const { values: o, positionals } = parsed;
+const [cmd, ...args] = positionals;
+const HELP = named(USAGE);
+if (o.help && COMMAND_HELP[cmd]) { console.log(named(COMMAND_HELP[cmd])); process.exit(0); }
+if (o.help || !cmd) { console.log(HELP); process.exit(0); }
+const num = (v) => (v == null ? undefined : Number(v));
+const opts = { ...o, count: num(o.count), scale: num(o.scale), samples: num(o.samples), shutter: num(o.shutter), fps: num(o.fps), workers: num(o.workers) };
+/* a number option out of its range is a wrong command (2), said before anything starts */
+const RANGES = { count: [1, 200, true], fps: [1, 240, true], scale: [0.1, 8, false], samples: [1, 64, true], shutter: [0, 1, false], workers: [1, 64, true] };
+for (const [name, [lo, hi, whole]] of Object.entries(RANGES)) {
+  const v = opts[name];
+  if (v === undefined || (Number.isFinite(v) && v >= lo && v <= hi && (!whole || Number.isInteger(v)))) continue;
+  console.error(`${RUN} ${cmd ?? ''}: --${name} is ${whole ? 'a whole number' : 'a number'} from ${lo} to ${hi}, not ${o[name]}`.replace(' :', ':'));
+  process.exit(2);
+}
+const commands = {
+  open: () => open(args[0] ?? null),
+  look: () => import('../src/look.mjs').then((m) => m.look(args, opts)),
+  render: () => import('../src/render.mjs').then((m) => m.render(args, opts)),
+};
+/**
+ * Show a project in Studio; `.film/opened` marks a project Studio has shown. A folder named is made a project when it is
+ * not one; with none, the project around the current folder, else the one opened last: the current folder (a code
+ * repository, the home folder) is never made a project unasked.
+ * @param {string | null} folder
+ */
+async function open(folder) {
+  /* a film on GitHub: copied into the library first, then opened as any folder */
+  if (folder != null && /^(https?:\/\/|(www\.)?(github|gitlab)\.com\/)/i.test(folder)) {
+    const fetched = await fetchFilm(folder);
+    if (!fetched.ok) return fetched;
+    folder = fetched.path;
+  }
+  const { openInStudio } = await import('../studio/client.mjs');
+  const { existsSync, mkdirSync, statSync, writeFileSync } = await import('node:fs');
+  const { dirname, join, resolve } = await import('node:path');
+  const fallback = process.env.AICUT_NO_BROWSER ? 0 : 15;
+  /* a person at a terminal has no browser of an agent's: theirs opens at once */
+  const now = !process.env.AICUT_NO_BROWSER && Boolean(process.stdout.isTTY && process.stdin.isTTY);
+  /* a checkout whose editor was never built (npm install builds it): Studio would show only that it is missing */
+  if (!existsSync(new URL('../studio/ui/dist/index.html', import.meta.url))) {
+    console.error('Studio\'s editor is not built in this checkout: run `npm run build:ui` (npm install does it).');
+  }
+  /** the project `from` is in (it, or a folder above it), if any */
+  const around = (from) => { for (let up = from; up !== dirname(up); up = dirname(up)) if (existsSync(join(up, 'film.html'))) return up; return null; };
+  let asked = folder == null ? around(process.cwd()) : resolve(folder);
+  if (asked && existsSync(asked) && !statSync(asked).isDirectory()) return { ok: false, usage: true, lines: [`${RUN} open: ${asked} is a file; a project is a folder`] };
+  /* a folder inside a project (scenes/, assets/) is the project around it, as look and render take it */
+  if (asked && existsSync(asked) && !existsSync(join(asked, 'film.html'))) asked = around(asked) ?? asked;
+  /* a code project is not a film: the film gets a folder of its own (a folder of media kept in git is fine) */
+  const MANIFESTS = ['package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', 'requirements.txt', 'Gemfile', 'pom.xml', 'build.gradle', 'composer.json', 'Package.swift'];
+  const code = (dir) => MANIFESTS.some((name) => existsSync(join(dir, name)));
+  if (asked && existsSync(asked) && !existsSync(join(asked, 'film.html')) && code(asked)) {
+    return { ok: false, usage: true, lines: [`${RUN} open: ${asked} is a code project, not a film; give the film a folder of its own: \`${RUN} open <name>\` makes <name>/ here`] };
+  }
+  try {
+    const { project, url, pages } = await openInStudio(asked, { fallback, now, say: (line) => console.error(line) });
+    if (project) {
+      mkdirSync(join(project.path, '.film'), { recursive: true });
+      writeFileSync(join(project.path, '.film', 'opened'), '');
+    }
+    /* an agent opens it in its own browser whatever else shows Studio: a page open elsewhere is not the agent's */
+    return { ok: true, lines: [project ? `project  ${project.path}` : `project  none yet: the person starts one in Studio, or \`${RUN} open <folder>\` makes one`, `Studio   ${url}`,
+      /* a page in sight switched to it: nothing more opens, nor should be opened */
+      pages ? '         already open in a browser, now showing this project: open nothing more'
+        : now ? '         opened in your browser'
+          : fallback ? `         open this address in your built-in browser now; with none, it opens in the person's browser in ${fallback} s`
+            : '         open this address in your built-in browser now, or give it to the person'] };
+  } catch (e) { return { ok: false, lines: [`${RUN} open: ${e.message}`] }; }
+}
+/**
+ * `aicut open <url>`: the repository or folder fetched into the projects library (studio/server/fetch-repo.mjs),
+ * its progress on stderr.
+ * @param {string} url
+ */
+async function fetchFilm(url) {
+  const { FetchError, fetchFilm: fetchInto, parseRepoUrl } = await import('../studio/server/fetch-repo.mjs');
+  const { libraryRoot } = await import('../studio/server/projects.mjs');
+  let source;
+  try { source = parseRepoUrl(url); } catch (e) { return { ok: false, usage: true, lines: [`${RUN} open: ${e.message}`] }; }
+  const mb = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  let said = '';
+  try {
+    const path = await fetchInto(source, {
+      library: libraryRoot(),
+      onProgress: ({ phase, bytes }) => {
+        const line = phase === 'lookup' ? `Looking up ${source.web}…` : phase === 'copy' ? `Fetched ${mb(bytes)}` : null;
+        if (line && line !== said) console.error((said = line));
+      },
+    });
+    return { ok: true, path };
+  } catch (e) {
+    return { ok: false, usage: e instanceof FetchError && ['url', 'host'].includes(e.code), lines: [`${RUN} open: ${e.message}`] };
+  }
+}
+if (!commands[cmd]) { console.error(`${RUN}: no command ${cmd}\n\n${HELP}`); process.exit(2); }
+
+if (cmd === 'look' || cmd === 'render') {
+  const { existsSync } = await import('node:fs');
+  const { dirname, join, resolve } = await import('node:path');
+  /* a project is made by \`open\`: look and render work in one (the one around here, or around what they look at) */
+  const around = (from) => { for (let up = resolve(from); up !== dirname(up); up = dirname(up)) if (existsSync(join(up, 'film.html'))) return up; return null; };
+  const target = args.find((a) => !/^\d+(\.\d+)?(-\d+(\.\d+)?)?$/.test(a));
+  const project = around('.') ?? (target ? around(target) : null);
+  if (!project) { console.error(`${RUN} ${cmd}: ${resolve('.')} is not in a project; \`${RUN} open\` makes one and shows it in Studio`); process.exit(2); }
+  /* a project Studio has never shown (copied, cloned, forked): show it now, so the person watches from the start */
+  if (!existsSync(join(project, '.film', 'opened'))) {
+    const shown = await open(project);
+    for (const line of shown.lines) console.error(line);
+    if (!shown.ok) console.error(`${RUN} ${cmd}: carrying on without Studio`);
+  }
+}
+
+/** The first run on a machine has no browser yet: fetch Playwright's Chromium once, then run the command again. */
+async function installChromium() {
+  const { createRequire } = await import('node:module');
+  const { spawnSync } = await import('node:child_process');
+  const { dirname, join } = await import('node:path');
+  const cli = join(dirname(createRequire(import.meta.url).resolve('playwright-core/package.json')), 'cli.js');
+  console.error(`${RUN}: first run on this machine, downloading the browser films are drawn in (about 100 MB, once)`);
+  const r = spawnSync(process.execPath, [cli, 'install', 'chromium-headless-shell'], { stdio: ['ignore', 'inherit', 'inherit'], windowsHide: true });
+  if (r.status !== 0) throw new Error('could not download the browser; run `npx playwright-core install chromium-headless-shell` and try again');
+}
+
+const FFMPEG_HELP = 'macOS: brew install ffmpeg · Debian/Ubuntu: sudo apt install ffmpeg · Windows: winget install ffmpeg';
+const noFfmpeg = async () => {
+  const { spawnSync } = await import('node:child_process');
+  return ['ffmpeg', 'ffprobe'].some((bin) => spawnSync(bin, ['-version'], { stdio: 'ignore', windowsHide: true }).error);
+};
+if ((cmd === 'look' || cmd === 'render') && await noFfmpeg()) {
+  console.error(`${RUN} ${cmd}: needs ffmpeg and ffprobe on the PATH (${FFMPEG_HELP})`);
+  process.exit(2);
+}
+if (cmd === 'open') {
+  /* Studio draws pages' pictures in the headless browser: make sure one is on disk before Studio starts, not after its
+     first try. Asked by looking at the file rather than by launching one, because a launch here spent 1.2 s of every
+     open; the browser itself is only brought up when a page actually has to be drawn. */
+  const { browserReady } = await import('../src/host.mjs');
+  if (!browserReady()) await installChromium();
+  if (await noFfmpeg()) console.error(`${RUN} ${cmd}: Studio needs ffmpeg for video pictures, sound waves and exports; install it (${FFMPEG_HELP})`);
+}
+
+try {
+  let result;
+  try { result = await commands[cmd](); }
+  catch (e) {
+    if (!/Executable doesn't exist/.test(e.message)) throw e;
+    await installChromium();
+    result = await commands[cmd]();
+  }
+  for (const line of result.lines) console.log(line);
+  if (result.ok === false) process.exitCode = result.usage ? 2 : 1;
+} catch (e) {
+  console.error(`${RUN} ${cmd}: ${e.message}`);
+  const { UsageError } = await import('../src/shared.mjs');
+  process.exit(e instanceof UsageError ? 2 : 1);
+}

package/package.json

@@ -1,6 +1,89 @@
-{
-  "name": "@autoaiai/aicut",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@autoaiai/aicut",
+  "version": "0.1.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "The open source AI video agent: films as web pages, the manual that teaches your coding agent to make them, the `aicut` command, and Studio, the editor to change anything in them.",
+  "license": "MIT",
+  "homepage": "https://aicut.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/autoaiai/aicut.git",
+    "directory": "packages/AiCut"
+  },
+  "bugs": {
+    "url": "https://github.com/autoaiai/aicut/issues"
+  },
+  "keywords": [
+    "video",
+    "motion-graphics",
+    "agents",
+    "claude-code",
+    "codex",
+    "animation",
+    "render"
+  ],
+  "type": "module",
+  "bin": {
+    "aicut": "bin/aicut.mjs"
+  },
+  "exports": {
+    "./film-doc": "./src/film-doc.mjs",
+    "./host": "./src/host.mjs",
+    "./shared": "./src/shared.mjs",
+    "./look": "./src/look.mjs",
+    "./render": "./src/render.mjs",
+    "./studio": "./studio/server/server.mjs",
+    "./studio-ui/*": "./studio/ui/src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "SPEC.md",
+    "TRADEMARK.md",
+    "bin",
+    "skills",
+    "src",
+    "!src/*.test.mjs",
+    "MANUAL.md",
+    "studio/server/**/*.mjs",
+    "studio/server/**/*.js",
+    "!studio/server/**/*.test.mjs",
+    "studio/client.mjs",
+    "studio/ui/dist",
+    "THIRD_PARTY_NOTICES.md",
+    "product.json"
+  ],
+  "engines": {
+    "node": ">=22.2"
+  },
+  "dependencies": {
+    "onnxruntime-node": "^1.30.0",
+    "playwright-core": "1.61.1"
+  },
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "test": "node --test --test-concurrency=1 --test-timeout=300000 src/*.test.mjs studio/*.test.mjs studio/server/*.test.mjs studio/server/providers/*.test.mjs studio/ui/src/editor/*.test.ts studio/ui/src/i18n/*.test.ts studio/ui/src/lib/*.test.ts studio/ui/src/components/*.test.ts",
+    "typecheck": "tsc -p studio/server && tsc -p studio/ui",
+    "build:ui": "vite build --config studio/ui/vite.config.ts",
+    "prepare": "npm run build:ui",
+    "prepack": "node scripts/product.mjs official",
+    "postpack": "node scripts/product.mjs restore"
+  },
+  "devDependencies": {
+    "@aicut/shared": "workspace:*",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "lucide-react": "^0.469.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.6"
+  }
+}

package/product.json

@@ -0,0 +1,5 @@
+{
+  "desktop": {
+    "updates": "https://aicut.dev/download/desktop"
+  }
+}

package/skills/aicut/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AiCut contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/aicut/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: aicut
+description: Make, edit, check and render videos with AICUT, where a film is a web page that draws any moment t. Use when the user asks for a video, launch film, explainer, motion graphics, animation, title sequence, music video or subtitles; to cut footage, pictures, voice-over, music and sound effects together; or to open AICUT Studio. Also for 做视频, 剪辑, 渲染, 动效, 字幕.
+license: MIT
+---
+
+# AICUT
+
+A film is `film.html`: it cuts animated web pages, footage, pictures and sound together on tracks. A page is a web
+page that sets `window.film = { frame(t) }` and draws that moment. Nothing else — no framework, no build step: an
+agent that knows the web already knows how to make one.
+
+## Read the manual first
+
+`aicut` prints its own manual: the format and the commands, about a thousand words, always the current version.
+
+```sh
+npx -y @autoaiai/aicut@latest
+```
+
+Run it before writing a film; `npx -y @autoaiai/aicut@latest <command> --help` has one command's options. That manual is
+authoritative — what follows is the workflow around it.
+
+## The loop
+
+1. **Open.** `npx -y @autoaiai/aicut@latest open <folder>` makes the folder a film (1920×1080, no tracks) and prints Studio's
+   address. Open that address in a browser you have: the person watches every change land there, and edits too.
+2. **Write.** `film.html` for the cut, one page per shot.
+3. **Check.** `npx -y @autoaiai/aicut@latest look` draws a contact sheet of the whole film, its sound and loudness, and checks
+   that the same `t` draws the same picture. `look 4.5` is one frame at full size, `look 3-6` a stretch,
+   `look assets/a.mp4` a media file. Look at the PNGs it writes; do not judge from the code.
+4. **Fix, repeat.** `render` only when the person asks for the file — they export from Studio themselves.
+
+Five shots are five pages cut together, not one page that changes scene: the person can then trim, reorder and
+replace each shot in Studio.
+
+## Hard rules
+
+- **The picture depends only on `t`.** Same `t`, same picture: no `Math.random()`, no `Date.now()`, no state carried
+  between calls, no animation loop, no autoplay. A page never animates by itself; the host calls `frame(t)`.
+- **Subtitles are never drawn in a page.** A sound or a video gets a WebVTT beside it with the same name
+  (`vo/1.wav` → `vo/1.vtt`); Studio makes the film's subtitles from those.
+- **Never cut, crop or re-encode media into new files.** A long recording is trimmed with `#t=in,out` on every clip
+  of it; CSS crops and scales.
+- **Sounds live in `film.html`, as clips.** A page has no sound. To place a hit heard at page time `t` inside a clip
+  that starts at `at` with in-point `in`: put it at `at + t - in` seconds of the film.
+- **The person is editing too.** Read `film.html` right before changing it, change only what you mean to, keep every
+  `overrides` as it is, and leave whatever the tools own (`.film/`, `.git/`, any dot directory) alone. Change nothing
+  on a track marked `locked`.
+- **Make what the person may change a DOM element.** Studio edits elements, not pixels: a headline belongs in an
+  `<h1>`, not painted into a canvas. A WebGL context needs `preserveDrawingBuffer: true`.
+- **Only what the film can use stays in `assets/`.** Delete the pieces you made the media from.
+
+## What is where
+
+- `references/film-format.md` — `film.html` and page rules on one page, when you want them in front of you.
+- `references/commands.md` — the four commands, their options, where output goes, what an exit code means.
+- `references/recipes.md` — snippets to copy: a title card, a canvas shot, picture-in-picture with voice-over and
+  subtitles, a music bed with a hit.
+- `references/troubleshooting.md` — a blank frame, a picture that changes on its own, a missing encoder.
+
+## Before you say it is done
+
+- `look` the whole film and read the sheet: framing, text fitting its box, nothing black where a picture should be.
+- The film plays the length the person asked for, with sound where they asked for it.
+- Say which files you made and what is in them; ask before rendering, unless they already asked for the MP4.

package/skills/aicut/references/commands.md

@@ -0,0 +1,72 @@
+# The commands
+
+Run them in the film's folder. `npx -y @autoaiai/aicut@latest` alone prints the manual; `--help` after a command prints that
+command's options; `--version` prints the version. Exit status: **0** done, **1** the film or the command failed (the
+output says why), **2** not a project or a wrong command.
+
+Use `npx -y @autoaiai/aicut@latest` rather than a bare `aicut` unless something put one on your PATH: it is the newest, and
+`npx` otherwise keeps the first version it ever fetched.
+
+## open
+
+```sh
+npx -y @autoaiai/aicut@latest open                    # the project around this folder, else the last one, else Studio's list
+npx -y @autoaiai/aicut@latest open launch-video       # a new film; the folder is made if missing
+npx -y @autoaiai/aicut@latest open .                  # this folder becomes the film
+npx -y @autoaiai/aicut@latest open https://github.com/aicut/examples/tree/main/one-prompt
+```
+
+- A folder that is not a project gets an empty `film.html`, 1920 × 1080 (its viewport `<meta>`), no tracks. A code
+  repository (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`…) gets a film folder of its own inside it.
+- A GitHub or GitLab address — a repository, or a folder in one (`…/tree/main/<folder>`) — is copied into the
+  projects library without its git history, then opened.
+- Starts Studio if it is not running and prints its address. **Open that address in your browser before writing
+  anything** and keep it open: the person watches every change land. A page already open switches to the project; if
+  no page connects within 15 s, Studio opens the person's own browser (`AICUT_NO_BROWSER=1`: never).
+
+## look
+
+```sh
+npx -y @autoaiai/aicut@latest look               # the whole film: contact sheet, sound, loudness, same-t check
+npx -y @autoaiai/aicut@latest look 4.5           # one frame, full size
+npx -y @autoaiai/aicut@latest look 3-6           # a stretch, densely
+npx -y @autoaiai/aicut@latest look assets/a.mp4  # a media file; also any .html page
+```
+
+Writes PNGs under `.film/cache/look/` and prints their paths. `--count <n>`: frames in a sheet (12). A project Studio
+has not shown yet is opened in Studio first, so the person watches it.
+
+## render
+
+```sh
+npx -y @autoaiai/aicut@latest render             # the whole film → <project>/<folder name>.mp4, beside film.html
+npx -y @autoaiai/aicut@latest render 12-20       # a range → .film/cache/render/
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--out <file>` | Another path; `.webm` or `.mov` with `--alpha` |
+| `--fps <n>` | Frame rate (30) |
+| `--4k` | 3840 px wide |
+| `--scale <n>` | Any device pixel ratio |
+| `--blur` | Motion blur (8 samples); `--samples <n>`, `--shutter <0..1>` |
+| `--alpha` | Transparent background |
+| `--workers <n>` | Parallel browsers |
+
+Only when the person asks for the file: you check with `look`, and they export from Studio.
+
+## get
+
+```sh
+npx -y @autoaiai/aicut@latest get                # what works right now, and which service makes the rest
+npx -y @autoaiai/aicut@latest get voice-over "A calm, low voice, 20 seconds"
+npx -y @autoaiai/aicut@latest get music "warm analog synth, 90 bpm"
+```
+
+Kinds: voice-over, music, sound effects, transcripts, images, image search, video, web search. Each works only once
+the person has connected a service that makes it, with their own key, in Studio → Settings → Providers (subtitle
+translation too). When a kind is not connected, tell the person which services make it and where to connect one
+rather than trying again. A video clip costs a lot: the person confirms it in Studio first.
+
+Save what you get under `assets/`. A generated sound or video gets its WebVTT beside it — that is where its words
+come from, not a page.

package/skills/aicut/references/film-format.md

@@ -0,0 +1,119 @@
+# The format, on one page
+
+The summary below is for having the rules in front of you. When it disagrees with `npx -y @autoaiai/aicut@latest` (the manual)
+or `packages/AiCut/SPEC.md` (the protocol, version 0.1), those are right.
+
+## The project
+
+| Path | What it is |
+| --- | --- |
+| `film.html` | The film: which clip plays when and where. The person edits it; read it before changing it. |
+| `*.html` | Pages: one per shot, each loading what it needs by relative path. |
+| `assets/` | Media (video, pictures, sound). Only what the film can use. |
+| `.film/`, `.git/`, dot files | The tools' own. Leave them alone. |
+
+## film.html
+
+```html
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=1920, height=1080">
+<style>.card { object-fit: cover; border-radius: 24px; }</style>
+</head>
+<body>
+<section>
+  <iframe src="title.html" style="left: 0; top: 0; width: 1920px; height: 1080px"></iframe>
+</section>
+<section>
+  <video src="assets/a.mp4#t=2,8" at="2" speed="0.5" volume="0.8" class="card"
+         style="left: 160px; top: 90px; width: 1600px; height: 700px"></video>
+</section>
+<section>
+  <audio src="assets/bed.mp3#t=0,14" volume="0.5"></audio>
+</section>
+</body>
+</html>
+```
+
+- The stage is the viewport's size in CSS pixels; without a `<meta name="viewport">`, 1920 × 1080. The head holds
+  styles and fonts and **no script**.
+- Each `<section>` is a track. The first is on top (titles before the footage they cover, background last). A track
+  has no kind; any clip goes on any track. Clips on one track never overlap — overlapping pictures go on different
+  tracks.
+- A track may be `hidden` (no picture, no sound), `muted` (no sound) or `locked` (the person's: change nothing on it).
+- A clip is one element and holds nothing: `<iframe>` a page, `<video>`, `<img>` a still, `<audio>` a sound.
+
+| Attribute | On | Meaning |
+| --- | --- | --- |
+| `src` | all | The file, relative to `film.html`. `#t=in,out` in the file's own seconds; `#t=in` to its end; nothing, all of it. A still, or a page without `duration`, **must** have `#t=0,length`. |
+| `id` | all | Unique in the film; without one, the file's name. |
+| `at` | all | The film second it starts at (default 0). |
+| `speed` | video, sound | 0.25–4, pitch kept. The clip lasts `(out − in) / speed`. |
+| `volume` | video, sound | Linear gain, 1 = the file's own level; `muted` = 0. |
+| `size` | page | `size="1920x1080"`: the pixels a page without its own `width`/`height` is laid out at (default: the stage). An editor writes it when the frame changes shape; keep it. |
+| `overrides` | all | The person's Studio changes, JSON. Keep as it is. |
+
+- **Placement is only** `left`, `top`, `width`, `height` (stage px) and `rotate` (degrees, clockwise about the center),
+  in the clip's `style`. `position`, `transform`, `margin` and the like on a clip are an error — the host places the
+  clip itself.
+- With only one of `width`/`height`, the other follows the picture's proportions. A video or still fills its box as
+  its CSS says (`object-fit: contain` unless the film says otherwise); without a box it is the stage. A page is
+  fitted whole inside its box, centered; without a box it is its own size, centered.
+- Look is CSS: `class`, the rest of `style` (`border-radius`, `clip-path`, `mask`, `filter`, `opacity`,
+  `mix-blend-mode`), and the film's `<style>`. **The film's CSS has no time** — what moves is a page.
+- `overrides` entries: `at` (a CSS selector, page clips only) with optional `n` (which match, from 1), `t` (translate
+  px), `s` (scale), `r` (rotate degrees), `style` (CSS, applied with priority), `text` (replaces the element's text),
+  `lock` (true: not selectable or movable; changes no pixels). One entry without `at`, on any clip, is the clip's own:
+  `{"fade": [in, out]}` in seconds — the picture's opacity and the sound's gain ramp 0→1 and 1→0.
+- Times are seconds to the millisecond; a host rounds each to three decimals. Read strictly: a misspelled attribute
+  is reported, not ignored.
+- A page clip is drawn at the page's local time `in + (t − at)`; past the page's `duration` it holds its last frame.
+
+## A page
+
+```js
+window.film = {
+  frame(t) { /* draw the whole picture at t seconds; may return a Promise */ },
+  duration: 12,                 // optional: its own length; without it, like a still
+  ready: loadEverything(),      // optional: Promise (or a function returning one) — frame is called after it
+  width: 480, height: 320,      // optional: a page that is part of the picture; without them, the stage
+};
+```
+
+- Set `window.film` before `load` (a module script does that).
+- **One rule: the picture depends only on `t`.** Repaint everything each call; never accumulate (`x += v`) across
+  calls. History (a trail, a physics run) is computed from `t` or precomputed during `ready`.
+- The host holds the page's clocks at `t` while it draws: `performance.now()`, `requestAnimationFrame` timestamps,
+  `Date`, CSS/Web Animations the page left running, and `Math.random` (seeded from `t`) all agree with it. Timers and
+  history do not — do not use them.
+- Libraries that run their own clock are driven by `t`: `timeline.seek(t)`, `animation.currentTime = t * 1000`,
+  `p5.redraw()`, `renderer.render(scene, camera)`.
+- Tweens that capture their start value the first time they run (GSAP `to`/`from`) depend on draw order: use
+  explicit start and end values (`fromTo`).
+- Lay the page out for `innerWidth × innerHeight`. A canvas should allocate
+  `innerWidth * devicePixelRatio` pixels.
+- WebGL: create the context with `preserveDrawingBuffer: true`.
+- Load web fonts per face (`document.fonts.load('700 64px …')`), not just `document.fonts.ready`.
+- A page opened as a plain web page has no `window.filmHost` and should play itself:
+  `if (!window.filmHost) { … requestAnimationFrame loop … }`. Optional, and it makes every film a page that just works.
+
+## Sound
+
+- A page has **no sound**. Every sound is a clip: an `<audio>`, or a `<video>`'s own sound.
+- A sound that belongs to a shot is placed at the film second the shot plays it. A hit heard at page time `t` in a
+  clip that starts at `at` with in-point `in` goes at **`at + t − in`**. Moving the page clip does not move it —
+  move them together.
+- The clip is silent when its `volume` is 0, or its track is `muted` or `hidden`.
+- Beat, onset and word timings are data, not API: precompute them into files the page reads during `ready`.
+
+## Words
+
+- What a sound or video says is a WebVTT beside it with the same name: `assets/vo/1.wav` → `assets/vo/1.vtt`, in the
+  file's own seconds. One cue per subtitle line; timestamp tags inside a cue time its words.
+- Translations sit beside it as `1.<language>.vtt`, the same lines at the same times.
+- A file starting with `NOTE Each cue is one subtitle, as cut by hand in AICUT Studio.` keeps its cues exactly as
+  they are.
+- **Never draw subtitles in a page.** Studio draws the film's subtitles from the clips that can be heard, placed by
+  their `at`, `#t=` and `speed`.