makaron-cli 0.13.7 → 0.13.9

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "description": "Give Claude Code a creative agent. Pass complete creative requests and source media to Makaron Chat.",
   "author": {
     "name": "Versa AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "description": "Give Codex a creative agent. Pass complete creative requests and source media to Makaron Chat.",
   "author": {
     "name": "Versa AI",

package/README.md

@@ -140,6 +140,20 @@ npx makaron-cli chat --project auto --image selfie.jpg --skill <marketplace-id-o
 
 `--skill` accepts an installed skill name, a marketplace UUID, or a unique marketplace label. If a marketplace skill is matched, the CLI installs or reuses it and sends `[Active skill: <installed-skill-name>]` to Makaron Agent. Ordinary users do not need admin commands, and the CLI intentionally does not expose skill deletion.
 
+### Built-in production skills
+
+Discover the available production workflows before choosing `--skill`:
+
+```bash
+npx makaron-cli skills list --built-in
+npx makaron-cli skills search "talking head captions" --built-in
+npx makaron-cli skills show talking-head --built-in
+npx makaron-cli chat --project auto --video talk.mp4 --skill talking-head -b "make a tight captioned edit"
+```
+
+The default list shows callable/discoverable skills with their purpose and input
+requirements. Add `--all` to include internal adapters and helper skills.
+
 ### With additional images (existing project)
 
 ```bash
@@ -246,7 +260,7 @@ npx makaron-cli chat --project <id> --video party.mp4 --image kid.jpg -b "make t
 npx makaron-cli chat --project <id> --video clip1.mp4 --video clip2.mp4 -b "splice these into one seamless video"
 ```
 
-Video files are uploaded via signed URL. CLI local video uploads support `.mp4`, `.mov`, or `.webm`, max 50MB, max 120s with 1s metadata tolerance, and <=1080p / 2,086,876 frame pixels. The frontend can transcode larger videos before upload; the CLI uploads directly to Storage and rejects videos above those limits.
+Video files are uploaded via signed URL. CLI local video uploads support `.mp4`, `.mov`, or `.webm`, max 50MB, max 900s (15 minutes) with 1s metadata tolerance, and <=1080p / 2,086,876 frame pixels. The frontend can transcode larger videos before upload; the CLI uploads directly to Storage and rejects videos above those limits.
 The agent understands video content natively — it can analyze scenes, edit, extend, and compose videos. Seedance video-reference editing is still limited to ~15s provider references, so longer uploaded videos should be split/prepared by the agent before model submission; Kling remains the base/direct edit path.
 Use `chat --project <id|auto> --video ...` for any project/timeline video work. Direct `video create` is standalone and does not write timeline entries.
 
@@ -363,7 +377,7 @@ For project/timeline video editing, use:
 npx makaron-cli chat --project <id|auto> --video input.mp4 -b "make it funny"
 ```
 
-Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests; MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio references through Makaron Agent/chat. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s; Grok 1.5 supports 1-15s single-image-to-video only; Gemini Omni supports 3-10s fast 720p image/video generation and editing with native generated audio, including up to 6 image references when no video reference is provided. For `--video-model grok`, forced `--aspect` is ignored to avoid xAI stretching the source image; pad/create the image at the target shape first or use another model.
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3|sync-lipsync-v3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests; MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio references through Makaron Agent/chat. `sync-lipsync-v3` requires exactly one video plus one MP3/WAV and preserves that replacement audio while aligning the mouth. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s; Grok 1.5 supports 1-15s single-image-to-video only; Gemini Omni supports 3-10s fast 720p image/video generation and editing with native generated audio, including up to 6 image references when no video reference is provided. For `--video-model grok`, forced `--aspect` is ignored to avoid xAI stretching the source image; pad/create the image at the target shape first or use another model.
 
 Seedance 2.5: use `--video-model seedance-2.5` for 4-30 second output at 480p/720p. `--image` accepts local files or URLs (up to 30), while repeatable `--video` and `--audio` accept up to 10 each. Use `--video-operation generate|edit|extend`, `--extend-direction forward|backward`, `--output-format mp4|mov`, `--web-search`, `--generated-audio` / `--no-generated-audio`, and `--relaxed-content-filter`. Edit/extend require a video reference. The Evolink route does not currently expose 4K output.
 
@@ -414,6 +428,7 @@ type CompletionAction = {
 3. Stop when `status` is `"completed"`, `"failed"`, or `"aborted"`
 4. Top-level `status: "completed"` means ALL artifacts are ready (including rendered videos)
 5. If an async video fails, top-level `status` is `"failed"` and the failed video may include `completion_actions` for a safe retry or diagnosis. Agents can surface these as the next user-confirmed step.
+6. `responses get --wait` reconciles pending video output against completed Project Media with the same `snapshot_id` or `task_id`. A lagging Run row therefore does not block delivery after the durable project video is ready.
 
 ## Exit Codes
 
@@ -494,6 +509,15 @@ send_message "All done!"
 
 Admin commands require an API key with admin privileges. Ask your admin to run `makaron admin set-admin <your-email>` to grant access.
 
+### Add credits to a user
+
+Use either the account email address or the Supabase user UUID. Credits must be a positive integer.
+
+```bash
+npx makaron-cli admin add-credits user@example.com 1000
+npx makaron-cli admin add-credits <user-id> 1000 --json
+```
+
 ### List all marketplace skills
 
 ```bash

package/bin/makaron.mjs

@@ -43,7 +43,7 @@ const SUPABASE_ANON_KEY = 'sb_publishable_FJFN2YYaWaQjABUKLqxQcA_fhxPLFDY';
 
 const MAX_VIDEO_UPLOAD_FILE_SIZE_MB = 50;
 const MAX_VIDEO_UPLOAD_FILE_SIZE = MAX_VIDEO_UPLOAD_FILE_SIZE_MB * 1024 * 1024;
-const MAX_VIDEO_UPLOAD_DURATION = 120;
+const MAX_VIDEO_UPLOAD_DURATION = 900;
 const MAX_VIDEO_UPLOAD_DURATION_TOLERANCE = 1;
 const MAX_VIDEO_PROVIDER_REFERENCE_DURATION = 15;
 const MAX_VIDEO_PROVIDER_REFERENCE_DURATION_TOLERANCE = 0.5;
@@ -328,6 +328,86 @@ function normalizeRunResponse(data) {
   return data;
 }
 
+function projectMediaIdentity(item) {
+  const snapshotId = item?.snapshot_id || item?.snapshotId;
+  const taskId = item?.task_id || item?.taskId;
+  return {
+    snapshotId: typeof snapshotId === 'string' && snapshotId ? snapshotId : null,
+    taskId: typeof taskId === 'string' && taskId ? taskId : null,
+  };
+}
+
+function findMatchingCompletedProjectVideo(item, media) {
+  const identity = projectMediaIdentity(item);
+  if (!identity.snapshotId && !identity.taskId) return null;
+  return (media || []).find(candidate => {
+    if (candidate?.type !== 'video' || candidate?.status !== 'completed' || !candidate?.url) return false;
+    const candidateIdentity = projectMediaIdentity(candidate);
+    return (identity.snapshotId && candidateIdentity.snapshotId === identity.snapshotId)
+      || (identity.taskId && candidateIdentity.taskId === identity.taskId);
+  }) || null;
+}
+
+async function reconcileRunWithProjectMedia(baseUrl, headers, data) {
+  normalizeRunResponse(data);
+  const output = Array.isArray(data.output) ? data.output : [];
+  const pendingVideos = output.filter(item =>
+    item?.type === 'video' && (item.status === 'queued' || item.status === 'rendering')
+  );
+  const agentDone = data.agent_status === 'completed'
+    || (data.status === 'in_progress' && data.incomplete === true);
+  if (!agentDone || pendingVideos.length === 0 || !data.projectId) return data;
+
+  let projectMedia;
+  try {
+    const res = await fetch(`${baseUrl}/api/projects/${data.projectId}/media`, { headers });
+    if (!res.ok) return data;
+    projectMedia = await res.json();
+  } catch {
+    return data;
+  }
+
+  let reconciled = false;
+  for (const item of pendingVideos) {
+    const completed = findMatchingCompletedProjectVideo(item, projectMedia.media);
+    if (!completed) continue;
+    const identity = projectMediaIdentity(completed);
+    item.status = 'completed';
+    item.url = completed.url;
+    if (identity.snapshotId) item.snapshot_id = identity.snapshotId;
+    if (identity.taskId) item.task_id = identity.taskId;
+    if (completed.posterUrl) item.poster_url = completed.posterUrl;
+    for (const field of ['duration', 'width', 'height']) {
+      if (typeof completed[field] === 'number') item[field] = completed[field];
+    }
+
+    const legacyVideos = Array.isArray(data.result?.videos) ? data.result.videos : [];
+    const legacy = legacyVideos.find(video => {
+      const legacyIdentity = projectMediaIdentity(video);
+      return (identity.snapshotId && legacyIdentity.snapshotId === identity.snapshotId)
+        || (identity.taskId && legacyIdentity.taskId === identity.taskId);
+    });
+    if (legacy) {
+      legacy.status = 'completed';
+      legacy.videoUrl = completed.url;
+      if (identity.snapshotId && !legacy.snapshotId) legacy.snapshotId = identity.snapshotId;
+    }
+    reconciled = true;
+  }
+
+  if (!reconciled) return data;
+  const pendingArtifacts = output.some(item =>
+    (item?.type === 'video' || item?.type === 'music')
+    && (item.status === 'queued' || item.status === 'rendering')
+  );
+  if (!pendingArtifacts) {
+    data.status = 'completed';
+    data.incomplete = false;
+    delete data.next_poll_after_ms;
+  }
+  return data;
+}
+
 function collectCompletionActions(data) {
   const items = [];
   const add = (action, source) => {
@@ -392,6 +472,11 @@ What you can ask:
   Marketplace skill
     makaron chat --project auto --image selfie.jpg --skill "Football Captain" "make this cinematic"
 
+  Built-in production skill
+    makaron skills list --built-in
+    makaron skills show talking-head --built-in
+    makaron chat --project auto --video talk.mp4 --skill talking-head "make a tight captioned edit"
+
   Fix one video moment from a screenshot
     makaron chat --project <id> --image screenshot.png "@4 this frame should be Paris; only fix this moment"
 
@@ -607,6 +692,7 @@ async function pollRun(baseUrl, headers, runId, opts = {}) {
         continue;
       }
       data = await res.json();
+      data = await reconcileRunWithProjectMedia(baseUrl, headers, data);
     } catch {
       continue;
     }
@@ -759,6 +845,7 @@ async function watchRun(baseUrl, headers, runId, opts = {}) {
         continue;
       }
       data = await res.json();
+      data = await reconcileRunWithProjectMedia(baseUrl, headers, data);
     } catch {
       await new Promise(r => setTimeout(r, interval));
       continue;
@@ -1174,12 +1261,29 @@ async function fetchBuiltInSkills(baseUrl) {
   return (data.skills || []).filter(skill => skill.builtIn);
 }
 
-function printBuiltInSkills(skills) {
+function isDiscoverableBuiltInSkill(skill) {
+  return skill.userSelectable !== false || skill.manifestVisible === true;
+}
+
+function builtInSkillSearchText(skill) {
+  return [
+    skill.name,
+    skill.label,
+    skill.description,
+    skill.studioRunRecipe,
+    skill.studioRunProfile,
+    skill.canonicalSkill,
+    ...(Array.isArray(skill.tags) ? skill.tags : []),
+  ].filter(Boolean).join(' ').toLowerCase();
+}
+
+function printBuiltInSkills(skills, opts = {}) {
   if (!skills.length) {
     console.log('No built-in skills found.');
     return;
   }
-  console.log(`Built-in skills: ${skills.length}\n`);
+  const heading = opts.heading || 'Built-in skills';
+  console.log(`${heading}: ${skills.length}\n`);
   for (const skill of skills) {
     const recipe = skill.studioRunRecipe ? `  [Studio Run: ${skill.studioRunRecipe}]` : '';
     const source = skill.sourceMediaRequired ? '  [source media required]' : '';
@@ -1189,6 +1293,30 @@ function printBuiltInSkills(skills) {
     console.log(`  ${skill.name}${recipe}${source}${adapter}`);
     if (skill.description) console.log(`    ${String(skill.description).replace(/\s+/g, ' ').trim()}`);
   }
+  if (opts.hint !== false) {
+    console.log('\nInspect and use a skill:');
+    console.log('  makaron skills show <name> --built-in');
+    console.log('  makaron chat --project auto --skill <name> "your request"');
+  }
+}
+
+function printBuiltInSkill(skill) {
+  const description = String(skill.description || '').replace(/\s+/g, ' ').trim();
+  console.log(`${skill.label || skill.name} (${skill.name})`);
+  if (description) console.log(`\nPurpose:\n  ${description}`);
+  console.log('\nBest input:');
+  console.log(`  ${skill.inputHint || (skill.sourceMediaRequired ? 'Source media is required. Attach it with --video, --image, or --audio as appropriate.' : 'Start from a clear brief; attach source media when the request depends on existing footage or assets.')}`);
+  if (skill.studioRunRecipe || skill.studioRunProfile) {
+    console.log('\nWorkflow:');
+    if (skill.studioRunRecipe) console.log(`  Studio Run recipe: ${skill.studioRunRecipe}`);
+    if (skill.studioRunProfile) console.log(`  Profile: ${skill.studioRunProfile}`);
+  }
+  if (Array.isArray(skill.tags) && skill.tags.length) {
+    console.log(`\nKeywords:\n  ${skill.tags.join(', ')}`);
+  }
+  console.log('\nUse with chat:');
+  const media = skill.sourceMediaRequired ? ' --video <file>' : '';
+  console.log(`  makaron chat --project auto${media} --skill ${skill.name} "describe the result you want"`);
 }
 
 function marketplaceSearchText(skill) {
@@ -1745,7 +1873,7 @@ Commands:
   video script|create|status         Video generation
   music create|status                Music generation
 
-  admin                              Admin commands (skills, upload, set-admin)
+  admin                              Admin commands (skills, credits, upload, set-admin)
 
 Examples:
   makaron chat --project auto "plan a launch poster"
@@ -1846,20 +1974,25 @@ function printHelp(topic, subtopic) {
   } else if (topic === 'install-skill') {
     console.log('Usage: makaron install-skill [--global] [--agent <agent>] [--yes]');
   } else if (topic === 'skills') {
-    if (subtopic === 'list') console.log('Usage: makaron skills list [--built-in] [--json]');
-    else if (subtopic === 'search') console.log('Usage: makaron skills search <query> [--json]');
-    else if (subtopic === 'show') console.log('Usage: makaron skills show <marketplace-id|label> [--json]');
+    if (subtopic === 'list') console.log('Usage: makaron skills list [--built-in] [--all] [--json]');
+    else if (subtopic === 'search') console.log('Usage: makaron skills search <query> [--built-in] [--all] [--json]');
+    else if (subtopic === 'show') console.log('Usage: makaron skills show <id|label|name> [--built-in] [--json]');
     else if (subtopic === 'install') console.log('Usage: makaron skills install <marketplace-id|label> [--json]');
     else console.log(`Skill commands:
-  skills list --built-in              List all built-in Makaron skills and Studio Run recipes
+  skills list --built-in              List user-facing built-in skills and what they do
+  skills list --built-in --all        Include internal/adapted helper skills
   skills list                         List marketplace skills
   skills search <query>               Search marketplace skills
+  skills search <query> --built-in    Find a built-in skill by task or keyword
   skills show <id|label> --built-in   Show a built-in skill
   skills show <id|label>              Show a marketplace skill
   skills install <id|label>           Install a marketplace skill to your workspace
 
 Use with chat:
   makaron chat --project auto --skill <id|label> "your request"
+
+Not sure which built-in skill to use? Start with:
+  makaron skills list --built-in
 `);
   } else if (topic === 'materialize') {
     console.log(`Usage: makaron materialize --project <id> (--media <N> | --snapshot <snapshotId> | --design-path <path> | --design-json <file|->) [--wait] [--publish|--no-publish] [--profile fast_720p|source] [--pick url|job_id|status]`);
@@ -1877,7 +2010,7 @@ Use with chat:
     console.log('Usage: makaron analyze --video <file|url> ["question"]');
   } else if (topic === 'video') {
     if (subtopic === 'script') console.log('Usage: makaron video script --image <file> [--image <file>] [--lang en|zh] "direction"');
-    else if (subtopic === 'create') console.log('Usage: makaron video create --script "..." [--image <url> ...] [--video <url> ...] [--audio <url> ...] [--duration 10] [--aspect 9:16] [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3] [--operation generate|edit|extend] [--video-resolution auto|480p|720p|768p|1080p|2k|4k] [--keep-original-sound]');
+    else if (subtopic === 'create') console.log('Usage: makaron video create --script "..." [--image <url> ...] [--video <url> ...] [--audio <url> ...] [--duration 10] [--aspect 9:16] [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3|sync-lipsync-v3] [--operation generate|edit|extend] [--video-resolution auto|480p|720p|768p|1080p|2k|4k] [--keep-original-sound]');
     else if (subtopic === 'status') console.log('Usage: makaron video status <taskId> | --snapshot <snapshotId> [--wait]');
     else console.log(`Video commands:
   video script --image <file> [--image <file>] "direction"   Write video script
@@ -1885,6 +2018,7 @@ Use with chat:
   video create --script "..." --video-model minimax-h3                          MiniMax H3 text-to-video (default 768P)
   video create --script "..." --image <url> [--duration 10]  Submit video task
   video create --script "..." --video <public-url> [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|google-omni|minimax-h3]  Edit/reference a video (Grok does not support video refs)
+  video create --script "Use the supplied audio" --video <url> --audio <url> --video-model sync-lipsync-v3  Lip-sync exact replacement audio
   video status <taskId>                                      Check video status
   video status --snapshot <snapshotId> [--wait]              Check v2 video snapshot
 `);
@@ -1900,6 +2034,7 @@ Use with chat:
     else if (subtopic === 'skill-categories') console.log('Usage: makaron admin skill-categories [--json|add|update|delete] ...');
     else if (subtopic === 'upload') console.log('Usage: makaron admin upload <local-file> <storage-path>');
     else if (subtopic === 'fetch-skill') console.log('Usage: makaron admin fetch-skill <share-code|url>');
+    else if (subtopic === 'add-credits') console.log('Usage: makaron admin add-credits <email-or-user-id> <credits> [--json]');
     else if (subtopic === 'set-admin') console.log('Usage: makaron admin set-admin <email>');
     else console.log(`Admin commands:
   admin skills                         List all marketplace skills
@@ -1912,6 +2047,7 @@ Use with chat:
   admin skill-categories delete <id>   Delete a category
   admin upload <file> <storage-path>   Upload file to Storage
   admin fetch-skill <code|url>         Download skill from share link
+  admin add-credits <user> <credits>   Add credits by email or user ID
   admin set-admin <email>              Grant admin access to a user
 `);
   } else if (topic === 'register') {
@@ -2257,7 +2393,8 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
         uploadedTurnVideoCount += videoSnaps.length;
         uploadedTurnMediaCount += videoSnaps.length;
       } else {
-        process.stderr.write(`⚠️ Failed to add videos: ${await res.text()}\n`);
+        process.stderr.write(`❌ Failed to add videos to the project timeline: ${await res.text()}\n`);
+        process.exit(1);
       }
     }
 
@@ -2346,7 +2483,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       const res = await fetch(`${baseUrl}/api/agent/run/${runId}`, { headers });
       if (!res.ok) { process.stderr.write(`Error ${res.status}: ${await res.text()}\n`); process.exit(1); }
       let data = await res.json();
-      normalizeRunResponse(data);
+      data = await reconcileRunWithProjectMedia(baseUrl, headers, data);
       if (exportCompositions && data.status === 'completed') {
         data = await exportAnimatedCompositionsFromRun(baseUrl, headers, data, { publish: publishExports, quiet: jsonOutput || !!pick });
       }
@@ -2485,22 +2622,41 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
 
   if (sub === 'list') {
     const builtIn = args.includes('--built-in');
-    const skills = builtIn ? await fetchBuiltInSkills(baseUrl) : await fetchMarketplaceSkills(baseUrl);
+    const allBuiltIn = args.includes('--all');
+    const fetchedSkills = builtIn ? await fetchBuiltInSkills(baseUrl) : await fetchMarketplaceSkills(baseUrl);
+    const skills = builtIn && !allBuiltIn
+      ? fetchedSkills.filter(isDiscoverableBuiltInSkill)
+      : fetchedSkills;
     if (jsonOutput) console.log(JSON.stringify({ skills }, null, 2));
-    else if (builtIn) printBuiltInSkills(skills);
+    else if (builtIn) printBuiltInSkills(skills, {
+      heading: allBuiltIn ? 'All built-in skills' : 'Built-in skills available to use',
+    });
     else printMarketplaceSkills(skills);
   } else if (sub === 'search') {
-    const query = args.filter((arg, index) => index > 1 && arg !== '--json').join(' ').trim();
-    if (!query) { console.error('Usage: makaron skills search <query> [--json]'); process.exit(1); }
+    const builtIn = args.includes('--built-in');
+    const allBuiltIn = args.includes('--all');
+    const query = args.filter((arg, index) => index > 1 && !['--json', '--built-in', '--all'].includes(arg)).join(' ').trim();
+    if (!query) { console.error('Usage: makaron skills search <query> [--built-in] [--all] [--json]'); process.exit(1); }
     const lowerQuery = query.toLowerCase();
     const slugQuery = slugifySkill(query);
-    const skills = (await fetchMarketplaceSkills(baseUrl))
-      .filter(skill => {
-        const rawMatch = marketplaceSkillTokens(skill).some(token => token.includes(lowerQuery));
-        const slugMatch = slugQuery ? marketplaceSearchText(skill).includes(slugQuery) : false;
-        return rawMatch || slugMatch;
-      });
+    const builtInQueryTokens = slugQuery.split('-').filter(Boolean);
+    const skills = builtIn
+      ? (await fetchBuiltInSkills(baseUrl))
+        .filter(skill => allBuiltIn || isDiscoverableBuiltInSkill(skill))
+        .filter(skill => {
+          const searchText = builtInSkillSearchText(skill);
+          const slugText = slugifySkill(searchText);
+          return searchText.includes(lowerQuery)
+            || (builtInQueryTokens.length > 0 && builtInQueryTokens.every(token => slugText.includes(token)));
+        })
+      : (await fetchMarketplaceSkills(baseUrl))
+        .filter(skill => {
+          const rawMatch = marketplaceSkillTokens(skill).some(token => token.includes(lowerQuery));
+          const slugMatch = slugQuery ? marketplaceSearchText(skill).includes(slugQuery) : false;
+          return rawMatch || slugMatch;
+        });
     if (jsonOutput) console.log(JSON.stringify({ skills }, null, 2));
+    else if (builtIn) printBuiltInSkills(skills, { heading: `Built-in skill matches for "${query}"` });
     else printMarketplaceSkills(skills);
   } else if (sub === 'show') {
     const identifier = args[2];
@@ -2512,7 +2668,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       : findMarketplaceSkill(skills, identifier);
     if (!skill) { console.error(`Skill not found: ${identifier}`); process.exit(1); }
     if (jsonOutput) console.log(JSON.stringify(skill, null, 2));
-    else if (builtIn) printBuiltInSkills([skill]);
+    else if (builtIn) printBuiltInSkill(skill);
     else printMarketplaceSkill(skill);
   } else if (sub === 'install') {
     const identifier = args[2];
@@ -2526,9 +2682,11 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     else console.log(data.skillName);
   } else {
     console.log(`Skill commands:
-  skills list --built-in              List all built-in Makaron skills and Studio Run recipes
+  skills list --built-in              List user-facing built-in skills and what they do
+  skills list --built-in --all        Include internal/adapted helper skills
   skills list                         List marketplace skills
   skills search <query>               Search marketplace skills
+  skills search <query> --built-in    Find a built-in skill by task or keyword
   skills show <id|label> --built-in   Show a built-in skill
   skills show <id|label>              Show a marketplace skill
   skills install <id|label>           Install a marketplace skill to your workspace
@@ -2695,6 +2853,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     const isSeedance25 = selectedVideoModel === 'seedance-2.5';
     const isSeedanceModel = selectedVideoModel === 'seedance-fast' || selectedVideoModel === 'seedance-mini' || selectedVideoModel === 'seedance' || isSeedance25;
     const isMinimaxH3 = selectedVideoModel === 'minimax-h3';
+    const isSyncLipsync = selectedVideoModel === 'sync-lipsync-v3';
     const supportsNativeTextToVideo = isSeedanceModel || isMinimaxH3;
     if (!script || (!images.length && !videos.length && !audios.length && !supportsNativeTextToVideo)) {
       console.error('Usage: makaron video create --script "..." [--image <url>] [--video <file|url>] [--audio <file|url>] [--duration 30] [--video-model seedance-2.5|minimax-h3]');
@@ -2706,6 +2865,10 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     if (isMinimaxH3 && images.length > 9) { console.error('MiniMax H3 supports at most 9 image references.'); process.exit(1); }
     if (isMinimaxH3 && videos.length > 3) { console.error('MiniMax H3 supports at most 3 video references.'); process.exit(1); }
     if (isMinimaxH3 && audios.length > 3) { console.error('MiniMax H3 supports at most 3 audio references.'); process.exit(1); }
+    if (isSyncLipsync && (images.length !== 0 || videos.length !== 1 || audios.length !== 1)) { console.error('Sync Lipsync v3 requires exactly one --video and one --audio, with no --image.'); process.exit(1); }
+    if (isSyncLipsync && !/<<<audio_1>>>/i.test(script)) {
+      script += '\nUse <<<audio_1>>> as the exact replacement soundtrack.';
+    }
     if (videoOperation && !['generate', 'edit', 'extend'].includes(videoOperation)) { console.error('--video-operation must be generate, edit, or extend.'); process.exit(1); }
     if (extendDirection && !['forward', 'backward'].includes(extendDirection)) { console.error('--extend-direction must be forward or backward.'); process.exit(1); }
     if (outputFormat && !['mp4', 'mov'].includes(outputFormat)) { console.error('--output-format must be mp4 or mov.'); process.exit(1); }
@@ -2715,8 +2878,9 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
       process.exit(1);
     }
 
-    const providerMaxDuration = isSeedance25 ? SEEDANCE25_MAX_VIDEO_REFERENCE_DURATION : MAX_VIDEO_PROVIDER_REFERENCE_DURATION;
-    const providerMaxPixels = isMinimaxH3 ? Infinity : isSeedance25 ? SEEDANCE25_MAX_VIDEO_FRAME_PIXELS : MAX_VIDEO_FRAME_PIXELS;
+    let providerMaxDuration = isSeedance25 ? SEEDANCE25_MAX_VIDEO_REFERENCE_DURATION : MAX_VIDEO_PROVIDER_REFERENCE_DURATION;
+    if (isSyncLipsync) providerMaxDuration = 60;
+    const providerMaxPixels = isSyncLipsync || isMinimaxH3 ? Infinity : isSeedance25 ? SEEDANCE25_MAX_VIDEO_FRAME_PIXELS : MAX_VIDEO_FRAME_PIXELS;
     const localImages = images.filter(image => !isHttpUrl(image));
     if (localImages.length) {
       const uploadedImages = await uploadImageFilesViaSignedUrl(baseUrl, headers, undefined, localImages);
@@ -2731,7 +2895,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
         maxDuration: providerMaxDuration,
         durationTolerance: MAX_VIDEO_PROVIDER_REFERENCE_DURATION_TOLERANCE,
         maxFramePixels: providerMaxPixels,
-        maxFileSize: isSeedance25 ? 200 * 1024 * 1024 : MAX_VIDEO_UPLOAD_FILE_SIZE,
+        maxFileSize: isSeedance25 || isSyncLipsync ? 200 * 1024 * 1024 : MAX_VIDEO_UPLOAD_FILE_SIZE,
         ...(selectedVideoModel === 'minimax-h3' ? {
           allowedExtensions: ['mp4', 'mov'],
           minSide: MINIMAX_H3_MIN_VIDEO_SIDE,
@@ -2757,7 +2921,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     const audioUrls = [];
     for (const audio of audios) {
       if (isHttpUrl(audio)) { audioUrls.push(audio); continue; }
-      const valid = validateAudioReferenceFile(audio, { maxDuration: isSeedance25 ? 30 : MAX_AUDIO_REFERENCE_DURATION });
+      const valid = validateAudioReferenceFile(audio, { maxDuration: isSyncLipsync ? 60 : isSeedance25 ? 30 : MAX_AUDIO_REFERENCE_DURATION });
       if (!valid.ok) { console.error(`❌ ${valid.error}`); process.exit(1); }
       process.stderr.write(`🎵 Uploading ${path.basename(audio)}...\n`);
       const uploaded = await uploadFileViaSignedUrl(baseUrl, headers, undefined, audio, valid.mime, { uploadKind: 'audio' });
@@ -2767,7 +2931,9 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     // Standalone MCP tool (no project timeline write)
     process.stderr.write('🎬 Submitting video...\n');
     const resolvedOperation = videoOperation || (isSeedance25 && videoUrls.length ? 'edit' : 'generate');
-    const vArgs = isSeedance25
+    const vArgs = isSyncLipsync
+      ? { script, images, videoUrls, audioUrls, videoModel: selectedVideoModel, videoResolution }
+      : isSeedance25
       ? { script, images, videoUrls, audioUrls, videoModel: selectedVideoModel, videoResolution, operation: resolvedOperation, extendDirection, outputFormat, generateAudio, contentFilter, webSearch }
       : isMinimaxH3
         ? { script, images, videoUrls, audioUrls, videoModel: selectedVideoModel, videoResolution }
@@ -2778,7 +2944,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     if (effectiveDuration) vArgs.duration = effectiveDuration;
     if (aspectRatio) vArgs.aspectRatio = aspectRatio;
     if (keepOriginalSound && videoUrls.length && !isSeedance25) vArgs.keepOriginalSound = true;
-    const result = await callMcpTool(baseUrl, headers, videoUrls.length && !isSeedance25 && !isMinimaxH3 ? 'makaron_edit_video' : 'makaron_create_video', vArgs);
+    const result = await callMcpTool(baseUrl, headers, videoUrls.length && !isSeedance25 && !isMinimaxH3 && !isSyncLipsync ? 'makaron_edit_video' : 'makaron_create_video', vArgs);
     const text = result?.content?.find(c => c.type === 'text')?.text;
     if (text) {
       console.log(text);
@@ -2825,6 +2991,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   video create --script "..." --video-model minimax-h3                          MiniMax H3 text-to-video (default 768P)
   video create --script "..." --image <url> [--duration 10]  Submit video task
   video create --script "..." --video <public-url> [--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|google-omni|minimax-h3]  Edit/reference a video (Grok does not support video refs)
+  video create --script "Use the supplied audio" --video <url> --audio <url> --video-model sync-lipsync-v3  Lip-sync exact replacement audio
   video status <taskId>                                      Check video status
   video status --snapshot <snapshotId> [--wait]              Check v2 video snapshot
 `);
@@ -3030,6 +3197,31 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
     if (!res.ok) { console.error(`Error ${res.status}:`, await res.text()); process.exit(1); }
     console.log(`✅ ${email} is now admin`);
 
+  } else if (sub === 'add-credits') {
+    const user = args[2]?.trim();
+    const credits = Number(args[3]);
+    if (!user || !Number.isSafeInteger(credits) || credits <= 0) {
+      console.error('Usage: makaron admin add-credits <email-or-user-id> <credits> [--json]');
+      console.error('Credits must be a positive integer.');
+      process.exit(1);
+    }
+
+    const res = await fetch(`${baseUrl}/api/admin/add-credits`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify({ email: user, credits }),
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      console.error(`Error ${res.status}:`, data?.error || 'Failed to add credits');
+      process.exit(1);
+    }
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(data));
+    } else {
+      console.log(`✅ Added ${credits} credits to ${user}. New balance: ${data.newBalance}`);
+    }
+
   } else {
     console.log(`Admin commands:
   admin skills                         List all marketplace skills
@@ -3042,6 +3234,7 @@ if (!command || command === '--help' || command === '-h' || command === 'help')
   admin skill-categories delete <id>   Delete a category
   admin upload <file> <storage-path>   Upload file to Storage
   admin fetch-skill <code|url>         Download skill from share link
+  admin add-credits <user> <credits>   Add credits by email or user ID
   admin set-admin <email>              Grant admin access to a user
 `);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makaron-cli",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "description": "Talk to Makaron Agent from the terminal — create projects, edit images, generate videos",
   "type": "module",
   "scripts": {

package/skills/makaron/SKILL.md

@@ -109,6 +109,33 @@ Returns immediately:
 | Beat-sync video from audio | `npx makaron-cli chat --project auto --audio beat.mp3 "use Seedance Mini at 480p to make a beat-synced video"` |
 | Create motion design | `npx makaron-cli chat --project <id> "make an animated Instagram story with this image"` |
 
+### Built-in production skills
+
+When the request names a production format or the correct workflow is unclear,
+discover the current built-in skills before starting. Do not guess a skill slug
+from memory: the server list is the source of truth.
+
+```bash
+# Short list of callable/discoverable production skills and their purpose
+npx makaron-cli skills list --built-in
+
+# Search by task, format, or keyword
+npx makaron-cli skills search "talking head captions" --built-in
+
+# Inspect input requirements, workflow, keywords, and exact invocation
+npx makaron-cli skills show talking-head --built-in
+
+# Use the exact slug returned by list/show
+npx makaron-cli chat --project auto --video talk.mp4 \
+  --skill talking-head -b "remove false starts, add synced captions and useful B-roll"
+```
+
+Use `--all` only when debugging adapters or looking for an internal helper Skill.
+For ordinary creative work, choose from the default built-in list. A named
+destination takes priority over a generic source workflow: for example,
+explicit TikTok/Douyin work uses `tiktok-video`; ordinary speech-led cleanup
+uses `talking-head`; broader mixed-footage editing uses `source-video-studio`.
+
 ### Marketplace skills
 
 Use marketplace skills when the user asks for a named Makaron effect, template, or skill such as "Football Captain", "足球队长", "World Cup MVP", or a marketplace UUID.
@@ -135,7 +162,7 @@ npx makaron-cli chat --project auto \
 
 `--skill` accepts an installed skill name, a marketplace UUID, or a unique marketplace label. Marketplace search matches every localized title, every localized default prompt, and category ids. If a marketplace skill is matched, the CLI installs or reuses it and sends `[Active skill: <installed-skill-name>]` to Makaron Agent. Do not call admin skill commands for ordinary users. There is intentionally no user-facing CLI delete command for marketplace skills.
 
-For an explicitly authorized marketplace administrator, `admin skills` shows category assignment and 4-locale title/prompt completeness, while `admin skill-categories` supports list/add/update/delete. New skills must include `en`, `zh`, `zh-Hant`, and `ja` in both `labels` and `prompts`, plus at least one existing `categories` id. Partial localized updates are safely merged server-side.
+For an explicitly authorized administrator, `admin add-credits <email-or-user-id> <positive-integer> [--json]` adds credits to a user. Marketplace administrators can use `admin skills` to see category assignment and 4-locale title/prompt completeness, while `admin skill-categories` supports list/add/update/delete. New skills must include `en`, `zh`, `zh-Hant`, and `ja` in both `labels` and `prompts`, plus at least one existing `categories` id. Partial localized updates are safely merged server-side.
 
 ### With additional images (existing project)
 
@@ -184,7 +211,7 @@ npx makaron-cli chat --project <id> --video clip1.mp4 --video clip2.mp4 -b "comb
 npx makaron-cli chat --project auto --video https://example.com/dance.mp4 -b "extend this to 15 seconds"
 ```
 
-Supported formats: MP4, MOV, WebM. CLI local video uploads support max 50MB, max 120s with 1s metadata tolerance, and <=1080p / 2,086,876 frame pixels. The frontend can transcode larger videos before upload; the CLI uploads directly to Storage and rejects videos above those limits. Videos are uploaded to the project timeline. The Agent can analyze scenes, edit content, compose multiple clips, extend duration, and add effects — all via natural language. Seedance video-reference editing is still limited to ~15s provider references, so longer uploaded videos should be split/prepared by the agent before model submission; Kling remains the base/direct edit path.
+Supported formats: MP4, MOV, WebM. CLI local video uploads support max 50MB, max 900s (15 minutes) with 1s metadata tolerance, and <=1080p / 2,086,876 frame pixels. The frontend can transcode larger videos before upload; the CLI uploads directly to Storage and rejects videos above those limits. Videos are uploaded to the project timeline. The Agent can analyze scenes, edit content, compose multiple clips, extend duration, and add effects — all via natural language. Seedance reference-video limits remain provider-specific, so longer uploaded videos should be split/prepared by the agent before model submission; Kling remains the base/direct edit path.
 
 Use `chat --project <id|auto> --video ...` for any project/timeline video work. Direct video commands are standalone raw-tool calls.
 
@@ -300,7 +327,7 @@ npx makaron-cli video status <taskId>
 npx makaron-cli chat --project <id|auto> --video input.mp4 -b "make it funny"
 ```
 
-Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests; MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio references through Makaron Agent/chat. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s; Grok 1.5 supports 1-15s single-image-to-video only; Gemini Omni supports 3-10s fast 720p image/video generation and editing with native generated audio, including up to 6 image references when no video reference is provided. For `--video-model grok`, forced `--aspect` is ignored to avoid xAI stretching the source image; pad/create the image at the target shape first or use another model.
+Options for `video create`: `--script "..."`, `--script-file <path>`, `--image <url>` (repeatable, up to the selected model limit), `--video <file|url>` and `--audio <file|url>` (repeatable where supported), `--duration <seconds>`, `--aspect 9:16|16:9|1:1`, `--video-model seedance-fast|seedance-mini|seedance|seedance-2.5|kling|grok|google-omni|minimax-h3|sync-lipsync-v3`, `--video-resolution auto|480p|720p|768p|1080p|2k|4k`. Default model is `seedance-fast`. SeeDance accepts native text-to-video with no image and integer output duration 4-15s (default 5s); `seedance-mini` supports 480p/720p and is best for cheaper drafts/multi-size tests; MiniMax H3 accepts native text-to-video, 4-15s output, public 768p/2k resolution, and up to 9 image, up to 3 video, and up to 3 audio references through Makaron Agent/chat. `sync-lipsync-v3` requires exactly one video plus one MP3/WAV and preserves that replacement audio while aligning the mouth. H3 defaults to 768p; request 2k explicitly for maximum/final quality. Kling supports 5-15s; Grok 1.5 supports 1-15s single-image-to-video only; Gemini Omni supports 3-10s fast 720p image/video generation and editing with native generated audio, including up to 6 image references when no video reference is provided. For `--video-model grok`, forced `--aspect` is ignored to avoid xAI stretching the source image; pad/create the image at the target shape first or use another model.
 
 Seedance 2.5 uses `--video-model seedance-2.5` and supports 4-30s at 480p/720p, up to 30 images + 10 videos + 10 audios, repeatable local/URL references, `--video-operation generate|edit|extend`, `--extend-direction`, `--output-format mp4|mov`, and `--web-search`. The Evolink route does not currently expose 4K output.
 
@@ -351,6 +378,7 @@ type CompletionAction = {
 3. Stop when `status` is `"completed"`, `"failed"`, or `"aborted"`
 4. Top-level `status: "completed"` means ALL artifacts are ready (including rendered videos)
 5. If an async video fails, top-level `status` is `"failed"` and the failed video may include `completion_actions` for a safe retry or diagnosis. Agents can surface these as the next user-confirmed step.
+6. `responses get --wait` reconciles pending video output against completed Project Media with the same `snapshot_id` or `task_id`. A lagging Run row therefore does not block delivery after the durable project video is ready.
 
 ## Exit Codes