@coppsary/motionly 1.0.2 → 1.1.0

package/README.md

@@ -210,14 +210,15 @@ 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 motionly skills add` (or `npx 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:
 
@@ -317,79 +318,29 @@ Known limitations:
 
 ---
 
-## Install from npm
+## Install and use
+
+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`.
 
-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.
+### Create a project
 
 ```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.
+`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.
 
-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.
-```
-
-Open `http://localhost:4173/editor` in your browser. Keep the terminal running while you edit and
-press `Ctrl+C` when finished.
-
-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:
+Skip the prompt with flags:
 
 ```bash
-motionly skills add
+npx motionly init demo --provider opencode   # install for one agent, no prompt
+npx motionly init demo --all                 # every supported agent
+npx motionly init demo --skip-skills          # no agent skills
 ```
 
-For scripts and CI, skip the wizard with flags:
+Provider names are `codex`, `claude`, `gemini`, `opencode`, and `kiro`. Use `--scope project` (default) or `--scope global` to install for every project on your machine.
 
-```bash
-motionly skills add --all --scope project
-motionly skills add --provider codex --scope global
-```
-
-Supported provider names are `claude`, `codex`, `gemini`, and `kiro`.
-
-### 3. Project layout
-
-The project contains:
+The scaffolded project:
 
 ```text
 demo/
@@ -400,29 +351,24 @@ demo/
 └── README.md
 ```
 
-### 4. Reopen the project later
+### Add skills to an existing project
 
 ```bash
-cd demo
-motionly dev
+npx motionly skills add                      # pick scope and agents
+npx motionly skills add --all --scope project
+npx 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 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 motionly`.
 
 ## Development from source
 

package/bin/motionly.js

@@ -14,14 +14,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 +116,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,7 +129,38 @@ 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) {
@@ -141,10 +187,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,19 +237,15 @@ 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();
   }
@@ -231,7 +270,21 @@ 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`);
     await serveEditor(argv, target);
@@ -367,12 +420,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 init <project-folder>            Create a project; asks which agent to set up
+  npx motionly init <folder> --provider codex   Create a project; install for one agent (no prompt)
+  npx motionly init <folder> --all              Create a project; install for every agent
+  npx motionly init <folder> --skip-skills      Create a project without agent skills
+  npx motionly skills add                       Install agent skills into an existing project
   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 motionly skills add --provider <codex|claude|gemini|opencode|kiro>
+  npx motionly dev [project-folder]             Reopen and edit a local project
 
 Options: --scope <project|global>, --port <number>, --no-open`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coppsary/motionly",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {

package/templates/motionly-skill/SKILL.md

@@ -7,6 +7,28 @@ description: Create, edit, validate, and preview editable Motionly .motion anima
 
 Motionly is a visual motion-graphics editor. Its editable source is `project.motion`; normal users refine it in the editor rather than hand-writing it. Keep generated source readable and load it through Motionly's parser and renderer.
 
+## Deep reference library
+
+This skill ships a full reference library beside this file at `references/`. This
+SKILL.md is only the quick contract — **before any non-trivial `.motion` work,
+open `references/llms.txt` and load the focused skills it lists**, then follow
+`references/AGENTS.md` for routing by intent:
+
+- `references/skills/motion-dsl/SKILL.md` — canvas, imports, elements, tracks, clips, audio, animations, keyframes, validation (load this first for any authoring or repair)
+- `references/skills/svg/SKILL.md` — logos, icons, diagrams, vector artwork, drawSVG, fill/stroke, local zoom/pan
+- `references/skills/animation/SKILL.md` and `references/skills/easing/SKILL.md` — choreography, presets, keyframes, timing
+- `references/skills/camera/SKILL.md` — global camera vs. local artwork focus
+- `references/skills/composition/SKILL.md` — hierarchy, spacing, color, brand, scene review
+- `references/skills/typography/SKILL.md` — titles, captions, kinetic type, narration timing
+- `references/skills/transitions/SKILL.md` — scene changes, wipes, crossfades, continuity
+- `references/skills/timeline/SKILL.md` — tracks, clips, trim, retime, overlap, audio placement
+- `references/skills/assets/SKILL.md` — PNG/JPEG, SVG, GIF, MP4, WebM, MOV, Lottie, codecs
+- `references/skills/rendering/SKILL.md` — preview, scrub, export, inspection, limitations
+- `references/skills/templates/SKILL.md` — product launch, logo reveal, diagram, social-stat storyboards
+
+Load only the topics the current task needs. The library is authoritative when it
+is more detailed than the summary below.
+
 ## Project and asset workflow
 
 - Read `AGENTS.md`, `project.motion`, and relevant files in `assets/` before editing.

package/templates/project/AGENTS.md

@@ -4,6 +4,26 @@ Keep Motionly simple and visual.
 
 Read the installed `motionly` skill before creating or substantially editing `project.motion`.
 
+## Agent Skill
+
+Installing the skill placed it at `.<agent>/skills/motionly/SKILL.md` (Codex uses
+`.agents/`, plus `.claude/`, `.gemini/`, `.opencode/`, or `.kiro/`). That file is the
+quick contract; a full reference library sits beside it under `references/` (`llms.txt`
+index plus focused skills: `motion-dsl`, `svg`, `animation`, `easing`, `camera`, `composition`,
+`typography`, `transitions`, `timeline`, `assets`, `rendering`, `templates`).
+
+Before writing or repairing `.motion` beyond a trivial edit:
+
+1. Read this file and `project.motion`.
+2. Open the skill `SKILL.md`, then `references/llms.txt`, and load
+   `references/skills/motion-dsl/SKILL.md` plus only the other reference skills the
+   task needs.
+3. Treat the reference library and Motionly's parser/renderer as authoritative over
+   the short summary below.
+
+If the skill was not installed, run `npx motionly skills add` to add it (with its
+reference library) for your agent.
+
 ## Product Rule
 
 Motionly is a motion graphics editor around `.motion`. The user edits visually; `.motion` is the saved source format underneath.