@coppsary/motionly 1.0.2 → 1.1.1

package/README.md

@@ -210,18 +210,20 @@ Open Motionly Assistant beside Assets, enter your own provider key, and describe
 
 **Model quality matters.** The AI model you choose directly affects composition, timing, and correct preset use. Smaller models may generate valid syntax but weaker visual decisions. Prefer a current, high-capability model with strong code-generation and instruction-following performance.
 
-For agents working inside the repository, use these files:
+For coding agents working inside a project, install the skill with `npx @coppsary/motionly skills add` (or `npx @coppsary/motionly init`, which asks which agent). This writes the `SKILL.md` contract plus a full `references/` library into your agent's folder — Codex (`.agents/`), Claude Code (`.claude/`), Gemini CLI (`.gemini/`), opencode (`.opencode/`), or Kiro (`.kiro/`):
 
 | Path | Purpose |
 |---|---|
-| `AGENTS.md` | Product scope and core `.motion` syntax |
-| `.agents/skills/write-motionly/SKILL.md` | Storyboard, timing, composition, asset, and validation workflow |
-| `.agents/skills/write-motionly/references/motion-syntax.md` | Supported syntax and preset reference |
-| `docs/agents/ai-authoring.mdx` | Prompting and project setup guide |
+| `<agent>/skills/motionly/SKILL.md` | Quick `.motion` contract |
+| `<agent>/skills/motionly/references/llms.txt` | Discovery index for the focused skills |
+| `<agent>/skills/motionly/references/skills/*/SKILL.md` | Full library: `motion-dsl`, `svg`, `animation`, `timeline`, and more |
+
+Point the agent at `AGENTS.md` and the installed `SKILL.md`, then let it load `references/llms.txt` and the reference skills the task needs. Working inside a clone of this repository instead? The same guidance lives at `AGENTS.md` and `.agents/skills/write-motionly/`. See the [AI Authoring Guide](docs/agents/ai-authoring.mdx) for prompting details.
 
 Use this short prompt with an LLM or agent working inside the repository:
 
 ```text
+/motionly
 Read AGENTS.md and .agents/skills/write-motionly/SKILL.md first.
 Inspect my assets, storyboard the animation, then create a valid .motion project.
 Use only supported Motionly syntax and presets. Keep one focal subject per shot,
@@ -317,79 +319,29 @@ Known limitations:
 
 ---
 
-## Install from npm
-
-Use the public `motionly` package from the npm registry. You do not need to clone this repository or download a tarball. Motionly requires Node.js `20.19.0` or newer.
-
-```bash
-npx motionly init demo
-```
-
-For the easiest project setup:
-
-1. Enter `2` to install the skills inside the new project.
-2. Enter `1` to install them for all supported agents.
-
-The complete terminal session looks like this:
-
-```text
-$ npx motionly init demo
-Created /path/to/workspace/demo
-
-Install Motionly agent skills?
-  1. Skip
-  2. Project — inside the new project
-  3. Global — every project for this user
-Select [1]: 2
-
-Which agents should receive the Motionly skill?
-  1. All supported agents
-  2. Claude Code
-  3. Codex
-  4. Gemini CLI
-  5. Kiro CLI
-Select [1]: 1
-
-Added claude: /path/to/workspace/demo/.claude/skills/motionly/SKILL.md
-Added codex: /path/to/workspace/demo/.agents/skills/motionly/SKILL.md
-Added gemini: /path/to/workspace/demo/.gemini/skills/motionly/SKILL.md
-Added kiro: /path/to/workspace/demo/.kiro/skills/motionly/SKILL.md
-
-  To reopen later: cd demo && npx motionly dev
-
-  Motionly is running.
-  Open this URL in your browser: http://localhost:4173/editor
-  Project: /path/to/workspace/demo
-  Press Ctrl+C to stop.
-```
+## Install and use
 
-Open `http://localhost:4173/editor` in your browser. Keep the terminal running while you edit and
-press `Ctrl+C` when finished.
+Motionly ships on npm — no clone and no global install. It needs Node.js `20.19.0` or newer, and every command runs through `npx`.
 
-Other wizard choices:
-
-- Choose **Skip** to create the project without agent skills.
-- Choose **Global** to make the selected skills available to every project for your user.
-- Choose one agent instead of **All supported agents** if you only use that agent.
-
-To install skills without creating a project:
+### Create a project
 
 ```bash
-motionly skills add
+npx @coppsary/motionly init demo
 ```
 
-For scripts and CI, skip the wizard with flags:
+`init` scaffolds the project and asks **which agent you're using**, then installs the Motionly agent skill for just that one (or choose "All supported agents"). Supported agents: **Codex, Claude Code, Gemini CLI, opencode, and Kiro**. The install is not a single file: it writes the `SKILL.md` contract plus a full `references/` library (`motion-dsl`, `svg`, `animation`, `timeline`, and more) with an `llms.txt` discovery index.
+
+Skip the prompt with flags:
 
 ```bash
-motionly skills add --all --scope project
-motionly skills add --provider codex --scope global
+npx @coppsary/motionly init demo --provider opencode   # install for one agent, no prompt
+npx @coppsary/motionly init demo --all                 # every supported agent
+npx @coppsary/motionly init demo --skip-skills          # no agent skills
 ```
 
-Supported provider names are `claude`, `codex`, `gemini`, and `kiro`.
+Provider names are `codex`, `claude`, `gemini`, `opencode`, and `kiro`. Use `--scope project` (default) or `--scope global` to install for every project on your machine.
 
-### 3. Project layout
-
-The project contains:
+The scaffolded project:
 
 ```text
 demo/
@@ -400,29 +352,24 @@ demo/
 └── README.md
 ```
 
-### 4. Reopen the project later
+### Add skills to an existing project
 
 ```bash
-cd demo
-motionly dev
+npx @coppsary/motionly skills add                      # pick scope and agents
+npx @coppsary/motionly skills add --all --scope project
+npx @coppsary/motionly skills add --provider codex --scope global
 ```
 
-Motionly opens `http://localhost:4173/editor`, loads `project.motion`, serves files from `assets/`, and saves editor changes back to the project. Use `--port <n>` to change the port or `--no-open` to skip opening the browser.
+Re-running is safe: existing skill files are kept, never overwritten.
 
-### Run without a global installation
-
-You can use the public package directly through `npx` instead:
+### Open and edit
 
 ```bash
-npx motionly --help
-npx motionly init my-video
+cd demo
+npx @coppsary/motionly dev
 ```
 
-For the no-setup browser editor:
-
-```bash
-npx motionly
-```
+Motionly opens `http://localhost:4173/editor`, loads `project.motion`, serves media from `assets/`, and saves editor changes back to the project. Add `--port <n>` to change the port or `--no-open` to skip launching the browser. For the no-setup browser editor, run `npx @coppsary/motionly`.
 
 ## Development from source
 

package/bin/ffmpeg-export.js

@@ -0,0 +1,263 @@
+import { Buffer } from 'node:buffer';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const jobs = new Map();
+const MAX_FRAME_BYTES = 100 * 1024 * 1024;
+const MAX_AUDIO_BYTES = 1024 * 1024 * 1024;
+
+/** Handle an export request in the standalone npm CLI server. */
+export async function handleFfmpegExportRequest(request, response) {
+  const url = new URL(request.url ?? '/', 'http://motionly.local');
+  if (!url.pathname.startsWith('/api/exports')) return false;
+
+  try {
+    await handleExportRequest(request, response, url);
+  } catch (error) {
+    if (response.headersSent) {
+      response.destroy(error instanceof Error ? error : new Error(String(error)));
+    } else {
+      response.statusCode = 500;
+      response.setHeader('content-type', 'text/plain;charset=utf-8');
+      response.end(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return true;
+}
+
+/** Connect-compatible middleware used by the Vite development and preview servers. */
+export function createFfmpegExportMiddleware() {
+  return (request, response, next) => {
+    void handleFfmpegExportRequest(request, response).then((handled) => {
+      if (!handled) next();
+    }, next);
+  };
+}
+
+async function handleExportRequest(request, response, url) {
+  if (request.method === 'POST' && url.pathname === '/api/exports') {
+    await createJob(request, response);
+    return;
+  }
+  const match = /^\/api\/exports\/([a-z0-9-]+)(?:\/(frames\/(\d+)|audio|finish))?$/.exec(
+    url.pathname
+  );
+  if (!match) return respond(response, 404, 'Unknown export endpoint');
+  const id = match[1];
+  const action = match[2];
+  if (!id) return respond(response, 404, 'Unknown export job');
+  const job = jobs.get(id);
+  if (!job) return respond(response, 404, 'Export job not found');
+
+  if (request.method === 'DELETE' && !action) {
+    jobs.delete(id);
+    await rm(job.directory, { recursive: true, force: true });
+    respond(response, 204);
+    return;
+  }
+
+  if (request.method === 'PUT' && action?.startsWith('frames/')) {
+    const index = Number(match[3]);
+    if (!Number.isInteger(index) || index < 0 || index >= job.totalFrames) {
+      return respond(response, 409, `Invalid frame ${index}`);
+    }
+    if (job.receivedFrames.has(index)) return respond(response, 409, `Duplicate frame ${index}`);
+    if (request.headers['content-type'] !== 'image/jpeg') {
+      return respond(response, 415, 'Export frames must be JPEG images');
+    }
+    await writeRequest(
+      request,
+      join(job.directory, `frame-${String(index).padStart(8, '0')}.jpg`),
+      MAX_FRAME_BYTES
+    );
+    job.receivedFrames.add(index);
+    respond(response, 204);
+    return;
+  }
+
+  if (request.method === 'PUT' && action === 'audio') {
+    if (!job.hasAudio) return respond(response, 409, 'This export was not created with audio');
+    await writeRequest(request, join(job.directory, 'audio-input'), MAX_AUDIO_BYTES);
+    job.audioReceived = true;
+    respond(response, 204);
+    return;
+  }
+
+  if (request.method === 'POST' && action === 'finish') {
+    if (job.receivedFrames.size !== job.totalFrames) {
+      return respond(
+        response,
+        409,
+        `Missing ${job.totalFrames - job.receivedFrames.size} export frames`
+      );
+    }
+    if (job.hasAudio && !job.audioReceived) {
+      return respond(response, 409, 'The attached audio file was not uploaded');
+    }
+    await finishJob(id, job, response);
+    return;
+  }
+
+  respond(response, 405, 'Method not allowed');
+}
+
+async function createJob(request, response) {
+  const input = JSON.parse((await readRequest(request, 64 * 1024)).toString('utf8'));
+  positiveInteger(input.width, 'width', 8192);
+  positiveInteger(input.height, 'height', 8192);
+  const fps = positiveNumber(input.fps, 'fps', 240);
+  const duration = positiveNumber(input.duration, 'duration', 24 * 60 * 60);
+  const totalFrames = positiveInteger(input.totalFrames, 'totalFrames', 24 * 60 * 60 * 240);
+  const audioStart = nonNegativeNumber(input.audioStart ?? 0, 'audioStart', duration);
+  const expectedFrames = Math.max(1, Math.ceil(duration * fps));
+  if (totalFrames !== expectedFrames) throw new Error(`Expected ${expectedFrames} frames`);
+  const id = randomUUID();
+  const directory = await mkdtemp(join(tmpdir(), 'motionly-export-'));
+  jobs.set(id, {
+    directory,
+    fps,
+    duration,
+    totalFrames,
+    receivedFrames: new Set(),
+    hasAudio: input.hasAudio === true,
+    audioStart,
+    audioReceived: false,
+  });
+  response.statusCode = 201;
+  response.setHeader('content-type', 'application/json');
+  response.end(JSON.stringify({ id }));
+}
+
+async function finishJob(id, job, response) {
+  const outputPath = join(job.directory, 'motionly.mp4');
+  const framePattern = join(job.directory, 'frame-%08d.jpg');
+  const args = [
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-y',
+    '-framerate',
+    String(job.fps),
+    '-start_number',
+    '0',
+    '-i',
+    framePattern,
+  ];
+  if (job.hasAudio) {
+    args.push('-itsoffset', String(job.audioStart), '-i', join(job.directory, 'audio-input'));
+  }
+  args.push('-map', '0:v:0');
+  if (job.hasAudio) args.push('-map', '1:a:0', '-c:a', 'aac', '-b:a', '192k');
+  args.push(
+    '-c:v',
+    'libx264',
+    '-preset',
+    'medium',
+    '-crf',
+    '18',
+    '-vf',
+    'pad=ceil(iw/2)*2:ceil(ih/2)*2:color=black,format=yuv420p',
+    '-frames:v',
+    String(job.totalFrames),
+    '-t',
+    String(job.duration),
+    '-movflags',
+    '+faststart',
+    outputPath
+  );
+
+  jobs.delete(id);
+  try {
+    await runFfmpeg(args);
+    const output = await stat(outputPath);
+    response.statusCode = 200;
+    response.setHeader('content-type', 'video/mp4');
+    response.setHeader('content-length', String(output.size));
+    await pipeline(createReadStream(outputPath), response);
+  } finally {
+    await rm(job.directory, { recursive: true, force: true });
+  }
+}
+
+function runFfmpeg(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ffmpeg', args, { windowsHide: true });
+    let errorOutput = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      errorOutput = `${errorOutput}${chunk}`.slice(-16_384);
+    });
+    child.once('error', (error) => {
+      reject(
+        error.code === 'ENOENT'
+          ? new Error('ffmpeg is not installed or is not available on PATH')
+          : error
+      );
+    });
+    child.once('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(errorOutput.trim() || `ffmpeg exited with code ${String(code)}`));
+    });
+  });
+}
+
+async function writeRequest(request, path, maxBytes) {
+  let size = 0;
+  const limiter = new Transform({
+    transform(chunk, _encoding, callback) {
+      size += chunk.byteLength;
+      callback(size > maxBytes ? new Error('Export upload is too large') : null, chunk);
+    },
+  });
+  try {
+    await pipeline(request, limiter, createWriteStream(path));
+  } catch (error) {
+    await rm(path, { force: true });
+    throw error;
+  }
+}
+
+async function readRequest(request, maxBytes) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.byteLength;
+    if (size > maxBytes) throw new Error('Export upload is too large');
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+function positiveInteger(value, name, max) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0 || value > max) {
+    throw new Error(`Invalid export ${name}`);
+  }
+  return value;
+}
+
+function positiveNumber(value, name, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > max) {
+    throw new Error(`Invalid export ${name}`);
+  }
+  return value;
+}
+
+function nonNegativeNumber(value, name, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > max) {
+    throw new Error(`Invalid export ${name}`);
+  }
+  return value;
+}
+
+function respond(response, status, message) {
+  response.statusCode = status;
+  if (message) response.setHeader('content-type', 'text/plain;charset=utf-8');
+  response.end(message);
+}

package/bin/motionly.js

@@ -2,6 +2,7 @@
 // Zero-dependency Motionly CLI and local editor server.
 
 import { createServer } from 'node:http';
+import { handleFfmpegExportRequest } from './ffmpeg-export.js';
 import { createInterface } from 'node:readline/promises';
 import { spawn } from 'node:child_process';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
@@ -14,14 +15,27 @@ const root = normalize(join(here, '..'));
 const dist = join(root, 'dist');
 const skillTemplatePath = join(root, 'templates', 'motionly-skill', 'SKILL.md');
 const projectTemplateRoot = join(root, 'templates', 'project');
+// The full, maintained skill library (llms.txt index + focused SKILL.md files).
+// It ships inside the published package and is installed beside the top-level
+// SKILL.md as a `references/` bundle so agents get real depth, not one file.
+const skillsLibraryRoot = join(root, 'motionly-skills');
 
 const PROVIDERS = {
-  claude: '.claude/skills/motionly/SKILL.md',
   codex: '.agents/skills/motionly/SKILL.md',
+  claude: '.claude/skills/motionly/SKILL.md',
   gemini: '.gemini/skills/motionly/SKILL.md',
+  opencode: '.opencode/skills/motionly/SKILL.md',
   kiro: '.kiro/skills/motionly/SKILL.md',
 };
 
+const AGENT_LABELS = {
+  codex: 'Codex',
+  claude: 'Claude Code',
+  gemini: 'Gemini CLI',
+  opencode: 'opencode',
+  kiro: 'Kiro',
+};
+
 const MIME = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
@@ -103,10 +117,12 @@ async function installSkills(base, providers) {
     throw new Error(`Unknown provider "${unknown}". Use: ${Object.keys(PROVIDERS).join(', ')}`);
 
   const source = await readFile(skillTemplatePath, 'utf8');
+  const libraryAvailable = await exists(skillsLibraryRoot);
   for (const provider of providers) {
     const relative = PROVIDERS[provider];
     const target = join(base, relative);
-    await mkdir(dirname(target), { recursive: true });
+    const skillDir = dirname(target);
+    await mkdir(skillDir, { recursive: true });
     try {
       await writeFile(target, source, { encoding: 'utf8', flag: 'wx' });
       console.log(`Added ${provider}: ${target}`);
@@ -114,9 +130,44 @@ async function installSkills(base, providers) {
       if (error.code !== 'EEXIST') throw error;
       console.log(`Kept ${provider}: ${target} already exists`);
     }
+    if (libraryAvailable) {
+      const added = await copyReferenceLibrary(skillsLibraryRoot, join(skillDir, 'references'));
+      if (added) console.log(`  + reference library: ${added} file${added === 1 ? '' : 's'}`);
+    }
   }
 }
 
+/**
+ * Recursively copy the discovery index and focused SKILL.md files from the
+ * skill library into an installed `references/` folder. Provider-specific
+ * `agents/` metadata is skipped, and existing files are never overwritten so
+ * user edits survive re-running the installer. Returns the number of new files.
+ */
+async function copyReferenceLibrary(source, destination) {
+  let copied = 0;
+  await mkdir(destination, { recursive: true });
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    if (entry.name === 'agents') continue;
+    const from = join(source, entry.name);
+    const to = join(destination, entry.name);
+    if (entry.isDirectory()) {
+      copied += await copyReferenceLibrary(from, to);
+    } else if (
+      entry.name === 'SKILL.md' ||
+      entry.name === 'llms.txt' ||
+      entry.name === 'AGENTS.md'
+    ) {
+      try {
+        await writeFile(to, await readFile(from), { flag: 'wx' });
+        copied += 1;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+      }
+    }
+  }
+  return copied;
+}
+
 async function choose(terminal, question, options) {
   console.log(`\n${question}`);
   options.forEach((option, index) => console.log(`  ${index + 1}. ${option.label}`));
@@ -141,10 +192,7 @@ async function selectSkillOptions(terminal, providers, scope) {
   if (!selectedProviders.length) {
     const provider = await choose(terminal, 'Which agents should receive the Motionly skill?', [
       { label: 'All supported agents', value: 'all' },
-      { label: 'Claude Code', value: 'claude' },
-      { label: 'Codex', value: 'codex' },
-      { label: 'Gemini CLI', value: 'gemini' },
-      { label: 'Kiro CLI', value: 'kiro' },
+      ...Object.keys(PROVIDERS).map((id) => ({ label: AGENT_LABELS[id], value: id })),
     ]);
     selectedProviders = provider === 'all' ? Object.keys(PROVIDERS) : [provider];
   }
@@ -194,26 +242,23 @@ async function resolveSkillOptions(argv) {
   return options;
 }
 
-async function promptForSkills(target) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-
+async function promptForAgent(scope) {
   const terminal = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const scope = await choose(terminal, 'Install Motionly agent skills?', [
-      { label: 'Skip', value: 'skip' },
-      { label: 'Project — inside the new project', value: 'project' },
-      { label: 'Global — every project for this user', value: 'global' },
+    const choice = await choose(terminal, 'Which agent are you using?', [
+      ...Object.keys(PROVIDERS).map((id) => ({ label: AGENT_LABELS[id], value: id })),
+      { label: 'All supported agents', value: 'all' },
     ]);
-    if (scope === 'skip') return;
-    const options = await selectSkillOptions(terminal, [], scope);
-    await installSkills(skillBase(options.scope, target), options.providers);
+    const providers = choice === 'all' ? Object.keys(PROVIDERS) : [choice];
+    return { providers, scope };
   } finally {
     terminal.close();
   }
 }
 
 async function initProject(name, argv = []) {
-  if (!name || name.startsWith('-')) throw new Error('Usage: npx motionly init <project-folder>');
+  if (!name || name.startsWith('-'))
+    throw new Error('Usage: npx @coppsary/motionly init <project-folder>');
   const target = resolve(name);
   if (await exists(target)) {
     if ((await readdir(target)).length) throw new Error(`Folder is not empty: ${target}`);
@@ -231,9 +276,23 @@ async function initProject(name, argv = []) {
   }
   await mkdir(join(target, 'assets'));
   console.log(`Created ${target}`);
-  await promptForSkills(target);
+  // Skills install unless opted out. Explicit --provider/--all/--scope flags win
+  // (non-interactive/CI). Otherwise, in a terminal, ask which agent to set up;
+  // with no terminal and no flags, default to every supported agent.
+  if (!argv.includes('--skip-skills') && !argv.includes('--no-skills')) {
+    const explicit = parseSkillOptions(argv);
+    const scope = explicit.scope ?? 'project';
+    let providers = explicit.providers;
+    if (!providers.length) {
+      providers =
+        process.stdin.isTTY && process.stdout.isTTY
+          ? (await promptForAgent(scope)).providers
+          : Object.keys(PROVIDERS);
+    }
+    if (providers.length) await installSkills(skillBase(scope, target), providers);
+  }
   if (process.stdin.isTTY && process.stdout.isTTY) {
-    console.log(`\n  To reopen later: cd ${name} && npx motionly dev`);
+    console.log(`\n  To reopen later: cd ${name} && npx @coppsary/motionly dev`);
     await serveEditor(argv, target);
   }
 }
@@ -282,6 +341,8 @@ async function serveEditor(argv, projectFolder = null) {
       const url = new URL(request.url ?? '/', 'http://localhost');
       const pathname = decodeURIComponent(url.pathname);
 
+      if (await handleFfmpegExportRequest(request, response)) return;
+
       if (projectPath && pathname === '/api/motion-project') {
         if (request.method === 'GET' || request.method === 'HEAD') {
           const source = await readFile(projectPath);
@@ -355,7 +416,7 @@ async function serveEditor(argv, projectFolder = null) {
   server.on('error', (error) => {
     if (error.code === 'EADDRINUSE') {
       console.error(
-        `Port ${port} is in use. Try: npx motionly ${projectRoot ? 'dev ' : ''}--port ${port + 1}`
+        `Port ${port} is in use. Try: npx @coppsary/motionly ${projectRoot ? 'dev ' : ''}--port ${port + 1}`
       );
       process.exitCode = 1;
       return;
@@ -367,12 +428,14 @@ async function serveEditor(argv, projectFolder = null) {
 function printHelp() {
   console.log(`Motionly
 
-  npx motionly                         Open the browser editor
-  npx motionly skills add              Pick project/global scope and agents
-  npx motionly skills add --provider <claude|codex|gemini|kiro>
-  npx motionly skills add --all
-  npx motionly init <project-folder>    Create and open a local project
-  npx motionly dev [project-folder]    Open and save a local project
+  npx @coppsary/motionly init <project-folder>            Create a project; asks which agent to set up
+  npx @coppsary/motionly init <folder> --provider codex   Create a project; install for one agent (no prompt)
+  npx @coppsary/motionly init <folder> --all              Create a project; install for every agent
+  npx @coppsary/motionly init <folder> --skip-skills      Create a project without agent skills
+  npx @coppsary/motionly skills add                       Install agent skills into an existing project
+  npx @coppsary/motionly skills add --all
+  npx @coppsary/motionly skills add --provider <codex|claude|gemini|opencode|kiro>
+  npx @coppsary/motionly dev [project-folder]             Reopen and edit a local project
 
 Options: --scope <project|global>, --port <number>, --no-open`);
 }
@@ -383,7 +446,7 @@ async function main() {
   if (command === 'skills') {
     if (subcommand !== 'add')
       throw new Error(
-        'Usage: npx motionly skills add [--provider <name> | --all] [--scope project|global]'
+        'Usage: npx @coppsary/motionly skills add [--provider <name> | --all] [--scope project|global]'
       );
     const options = await resolveSkillOptions(argv.slice(2));
     await installSkills(skillBase(options.scope, process.cwd()), options.providers);