ugcinc 4.26.0 → 4.26.1

package/README.md

@@ -484,3 +484,34 @@ Inputs: HTTPS image URL and integer display-oriented pixel `box` with a small pl
 Fitting runs locally through the installed UGC ImageEditorComposition, searching the supported TikTok Sans, SF Pro and Arial-stack choices, weight, size, spacing, line height, alignment and outline. Fill/background/outline colors are estimated from the crop. Arial may use a system fallback; original font identity is always `unverified`. No custom font upload, gradients, perspective, mixed styles, emoji or shadow setting is inferred. Busy borders, blank crops and clipped foreground return explicit unavailable results. These checks do not prove that every remaining crop is suitable: inspect residuals and preview.
 
 Returns up to three candidates, renderable settings, `maskIoU`, `foregroundMae` (mean absolute RGB error on the union of reference/rendered ink, scaled0–1), and an owned reference/render/difference preview plus JSON manifest. `quality: 'close'` means IoU>=0.9 and foreground MAE<=0.1; otherwise `approximate`. These are image-fit measures, not font-recognition probabilities or content-quality scores. Single-line alignment/padding cannot be uniquely recovered; returned geometry reproduces visible positioning. Render count, installed UGC version and bundled font hashes are included. Search is capped at320 renders and a480-second search budget within existing job limits; resource failures are explicit failed jobs. The renderer bundle is reused unchanged, with no hosted inference or new font downloads.
+
+## Agent media inspection and content workflows
+
+Install or refresh the bundled Claude Code instructions in the agent's project:
+
+```bash
+npx ugcinc@4.26.1 init --update media content-automation automations
+```
+
+`init` preserves existing files by default. `--update` writes changed skill files
+and backs up their previous contents under the project's `.ugcinc/skill-backups/`.
+Optional skill names limit installation/update to those skills. New `media` and
+`content-automation` skills include linked tool/reference guides; no account,
+schedule or publishing changes are performed by installation.
+
+Use `UGC_API_KEY` for an existing org-scoped key. When that key already lives in
+an app env file, set `UGC_ENV_FILE` to its path instead of copying the file/key.
+Set `UGC_ORG_ID` in that file or the process environment to select the intended
+organization; a JSON `orgId` overrides that default.
+Environment credentials take precedence over the explicit env file, then saved
+UGC CLI configuration and existing `.env` lookup. Acquisition and analysis need
+`content:analyze` for restricted keys. The CLI can discover tool names with
+`npx ugcinc --list`; JSON parameters/limits are documented in the media skill.
+
+The media skill covers all eleven shipped acquisition/inspection operations,
+including text-style fitting and the supporting analysis-status helper. The
+content-automation skill covers reusable workflow inputs, real-reference review,
+layout/readability, asset identity, procedural animation, CTA and audio handling.
+It distinguishes measured facts from inference and requires verified public
+HTTPS previews. SAM-dependent capabilities remain deferred and are not advertised
+as available tools. A successful API call alone does not certify content quality.

package/dist/cli.js

@@ -72,6 +72,11 @@ function saveConfig(config) {
 function loadEnvVar(name) {
     if (process.env[name])
         return process.env[name];
+    if (process.env.UGC_ENV_FILE) {
+        const value = checkEnvFile(path.resolve(process.env.UGC_ENV_FILE), name);
+        if (value)
+            return value;
+    }
     // Check ~/.ugcinc/config.json
     const config = loadConfig();
     if (name === 'UGC_API_KEY' && config.apiKey)
@@ -104,10 +109,12 @@ function printUsage() {
     console.log('');
     console.log('Commands:');
     console.log('  auth <api_key> [--admin]      Save API key (use --admin for admin keys)');
-    console.log('  init                          Set up Claude Code skills in your project');
+    console.log('  init [--update] [skills...]    Install skills; --update backs up changed files');
     console.log('  <tool_name> [json_params]     Run an API tool');
     console.log('  --list                        List all available tools as JSON');
     console.log('  --help                        Show this help message');
+    console.log('  UGC_ENV_FILE                  Read credentials from an existing env file');
+    console.log('  UGC_ORG_ID                    Default organization (JSON orgId takes priority)');
     console.log('');
     console.log('Available tools:');
     for (const tool of tools_1.allTools) {
@@ -130,20 +137,47 @@ function runAuth(args) {
     if (config.admin === 'true')
         console.log('Mode: admin');
 }
-function runInit() {
+function runInit(args) {
     const cwd = process.cwd();
     const skillsDir = path.join(cwd, '.claude', 'skills');
+    const update = args.includes('--update');
+    const requested = args.filter(arg => !arg.startsWith('--'));
+    const known = new Set(Object.keys(skills_1.skillFiles).map(name => name.split('/')[0] ?? ''));
+    const unknown = args.filter(arg => arg.startsWith('--') && arg !== '--update');
+    const invalid = requested.filter(name => !known.has(name));
+    if (unknown.length || invalid.length) {
+        console.error('Unknown skill or option: ' + [...unknown, ...invalid].join(', '));
+        process.exit(1);
+    }
     let created = 0;
     let skipped = 0;
+    let updated = 0;
+    let backupDir;
     for (const [skillPath, content] of Object.entries(skills_1.skillFiles)) {
+        if (requested.length && !requested.includes(skillPath.split('/')[0] ?? ''))
+            continue;
         const fullPath = path.join(skillsDir, skillPath);
         const dir = path.dirname(fullPath);
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
         if (fs.existsSync(fullPath)) {
-            skipped++;
-            console.log(`  skip  ${skillPath} (already exists)`);
+            if (!update || fs.readFileSync(fullPath, 'utf-8') === content) {
+                skipped++;
+                console.log(`  skip  ${skillPath} (already exists${update ? '; unchanged' : ''})`);
+                continue;
+            }
+            if (!backupDir) {
+                const base = path.join(cwd, '.ugcinc', 'skill-backups');
+                fs.mkdirSync(base, { recursive: true });
+                backupDir = fs.mkdtempSync(path.join(base, 'update-'));
+            }
+            const backup = path.join(backupDir, skillPath);
+            fs.mkdirSync(path.dirname(backup), { recursive: true });
+            fs.copyFileSync(fullPath, backup, fs.constants.COPYFILE_EXCL);
+            fs.writeFileSync(fullPath, content);
+            updated++;
+            console.log(`  update ${skillPath} (previous copy backed up)`);
         }
         else {
             fs.writeFileSync(fullPath, content);
@@ -152,7 +186,9 @@ function runInit() {
         }
     }
     console.log('');
-    console.log(`Done! Created ${created} skill files${skipped > 0 ? `, skipped ${skipped} existing` : ''}.`);
+    console.log(`Done! Created ${created}, updated ${updated}, skipped ${skipped} skill files.`);
+    if (backupDir)
+        console.log('Backups: ' + backupDir);
     console.log('');
     console.log('Next steps:');
     console.log('  1. Set your API key:  npx ugcinc auth <your-api-key>');
@@ -162,6 +198,7 @@ function runInit() {
     console.log('  /accounts     Manage accounts, warmup, and social profiles');
     console.log('  /posts        Schedule, update, and manage posts');
     console.log('  /media        Manage media library and social audio');
+    console.log('  /content-automation  Develop and review reusable content workflows');
     console.log('  /automations  Run and manage automation workflows');
     console.log('  /stats        View account and post statistics');
 }
@@ -191,8 +228,12 @@ async function runTool(toolName, rawParams) {
         delete parsed.orgId;
     }
     const config = loadConfig();
-    const isAdmin = config.admin === 'true';
-    const client = new client_1.UGCClient({ apiKey, orgId: orgId ?? config.orgId, admin: isAdmin });
+    const explicitEnvKey = process.env.UGC_API_KEY;
+    const explicitFileKey = process.env.UGC_ENV_FILE
+        ? checkEnvFile(path.resolve(process.env.UGC_ENV_FILE), 'UGC_API_KEY') : undefined;
+    const usesSavedKey = !explicitEnvKey && !explicitFileKey && apiKey === config.apiKey;
+    const isAdmin = usesSavedKey && config.admin === 'true';
+    const client = new client_1.UGCClient({ apiKey, orgId: orgId ?? loadEnvVar('UGC_ORG_ID') ?? (usesSavedKey ? config.orgId : undefined), admin: isAdmin });
     let params = undefined;
     if (parsed) {
         const parseResult = tool.schema.safeParse(parsed);
@@ -239,7 +280,7 @@ async function main() {
         process.exit(0);
     }
     if (args[0] === 'init') {
-        runInit();
+        runInit(args.slice(1));
         process.exit(0);
     }
     await runTool(args[0], args[1]);

package/dist/content-skills.d.ts

@@ -0,0 +1 @@
+export declare const contentSkillFiles: Record<string, string>;

package/dist/content-skills.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentSkillFiles = void 0;
+// Generated by scripts/build-skills.cjs; edit skills/** instead.
+exports.contentSkillFiles = {
+    "media/SKILL.md": "---\nname: media\ndescription: Acquire TikTok and Instagram posts and inspect images, video and audio with UGC Inc tools. Use for reference analysis, OCR, frames, scenes, transcription, colors, layout, text-style fitting, or media-library management.\nallowed-tools: Bash, Read\n---\n\nUse the installed UGC Inc CLI:\n\n```bash\nnpx ugcinc --list\nnpx ugcinc <tool_name> '<json_params>'\n```\n\nCredentials come from `UGC_API_KEY` or existing UGC configuration. Use the user's\norganization and a key with `content:analyze` for acquisition/analysis. If using\nan admin key, pass the authorized `orgId` in the JSON parameters. Do not print\ncredentials, copy an administrator key to another user's machine, or change\norganizations to bypass a denial. Confirm access with one small tool call.\nIf credentials already live in an app env file, set `UGC_ENV_FILE` to that file's\npath so the CLI reads the existing key without duplicating its contents. Set\n`UGC_ORG_ID` in that file or the process environment to scope calls to the user's\norganization; an explicit JSON `orgId` takes priority.\n\nRead [references/tools.md](references/tools.md) for request shapes, result fields\nand limits. The CLI lists names/descriptions; the reference explains parameters.\n\n## Choose the input and tools\n\n- A profile URL: `list_profile_posts` discovers a bounded page; follow its cursor\n  only as needed. Listing does not download media or guarantee complete history.\n- A post URL: `download_social_post` ingests its ordered assets into owned media.\n  Use returned asset URLs for analysis; the TikTok/Instagram HTML URL is not a\n  video file. Check complete/partial/failed status and failed assets.\n- A direct media URL: use the corresponding inspection tool directly.\n- Video: `detect_scenes`, `extract_frames`, `read_video_text`; audio tools accept\n  video too. Inspect multiple moments, including changes near the beginning/end.\n- Image: `read_image_text`, `sample_colors`, `measure_layout` using supplied\n  boxes/masks, and `match_text_style` for a specified text crop.\n- Audio: `transcribe_audio` and `measure_audio_levels`.\n\nThe SDK/CLI waits for processing automatically. Check both the outer response's\n`ok` and the returned job's `status`. Analysis is usable when\n`data.status === \"completed\"`; its content is `data.result`. If still pending or\nprocessing, keep its job ID and use `get_media_analysis` rather than resubmitting.\nUse bounded retries for retryable failures; report persistent errors/partial\ncoverage. A zero process exit code alone does not establish API success.\n\n## Interpret evidence accurately\n\n- Coordinates are display-oriented source pixels; times are source-relative\n  milliseconds. Use returned decoded timestamps, dimensions and coverage.\n- OCR is English, may miss stylized text, and can be empty on unreadable input.\n  `fast` video OCR leaves uninspected intervals. `frame_scan` is bounded and\n  cannot inspect an arbitrarily long clip in one request.\n- Speech timestamps are estimates; speaker labels/forced alignment are absent.\n  A transcript does not establish music, emotion, delivery or sound effects.\n- Color sampling measures decoded sRGB pixels, not guaranteed design hex values.\n  Layout measurement does not detect objects or recover original layer files.\n- Text-style matching returns supported UGC settings and visual residuals. Font\n  identity is unverified; inspect the preview before calling a fit accurate.\n  It has a restricted ASCII/font/style surface; the native TikTok renderer is a\n  separate bounded rendering capability, not proof that matching is exact.\n- SAM/object segmentation, automatic overlay detection, element/mask tracking,\n  motion measurement, extraction, media comparison/alignment and semantic search\n  are not available through this tool set. Do not invent those calls or install\n  SAM. Existing OCR text tracks remain available.\n\n## Review and share media\n\nOpen returned image/contact-sheet previews and review the relevant sequence.\nWhen the agent runtime can consume audio/video, use it. Otherwise use the\navailable transcript, audio preview and level measurements and explicitly state\nwhat was not listened to or inspected. Do not claim to have watched/listened\nbecause an analysis request succeeded.\n\nShare only verified browser-accessible HTTPS artifacts. Fetch without auth and\ncheck status, content type and decoding; for video also check byte-range support.\nUse the returned owned-media URLs. Local paths, localhost/private addresses and\nexpiring upstream CDN links are not deliverable previews. If an artifact needs\nuploading, use the supported owned storage path; do not claim a file is hosted\nbecause a media record was created for an arbitrary URL.\n\nFor building a reusable content format, use the `content-automation` skill.\n",
+    "media/references/tools.md": "# UGC media tool requests and results\n\nRun `npx ugcinc TOOL 'JSON'`. Shell quoting varies on Windows; if the shell\nchanges the JSON, use a small Node script with `UGCClient` and its `media`\nmethods instead of repeatedly sending malformed requests. For example:\n\n```js\nconst { UGCClient } = require('ugcinc');\nconst client = new UGCClient({\n  apiKey: process.env.UGC_API_KEY,\n  orgId: process.env.UGC_ORG_ID,\n});\n// Use admin:true only with an authorized administrator credential.\n```\n\nRequest URLs must be HTTPS. Analysis source URLs must not contain credentials\nor fragments. Image operations support still PNG/JPEG/WebP, at most4096pixels\nper side; the shared download limit is100MiB. Geometry must fit the actual\ndisplay-oriented source. Respect more restrictive operation limits below.\n\n## Acquisition\n\n| CLI tool / SDK method | Parameters | Result |\n| --- | --- | --- |\n| `list_profile_posts` / `media.listProfilePosts` | `{url, limit?, cursor?}`; TikTok/Instagram profile; limit1–50 | `data.posts`, profile metadata, continuation cursor. Follow the actual returned cursor, not a fabricated page number. |\n| `download_social_post` / `media.downloadSocialPost` | `{url}`; canonical TikTok/Instagram post URL | `data.status`, `assets[]` in order, `failedAssets[]`, `manifestUrl`, post/sound metadata. Each asset has `url`, `mediaId`, dimensions, type, duration, audio presence and hash. Repeat the same URL to resume retryable partial imports. |\n\nEmbedded video audio remains attached. Photo assets have no embedded soundtrack;\nsound attribution does not mean audio bytes were downloaded. Preserve sound\nID/link separately; never replace a post excerpt with the full sound-page track\nand call them identical. Partial imports are not a complete carousel.\n\n## Analysis\n\nThese return `{ok, data:{jobId,status,operation,result?,error?}}`. Use the completed\n`data.result` fields listed below. Failure can occur after successful submission.\n\n| CLI tool / SDK method | Parameters | Result content |\n| --- | --- | --- |\n| `extract_frames` / `media.extractFrames` | `{url,timestampsMs:[0,1500,3000],selection:\"nearest\",contactSheet:true}` OR `{url,range:{startMs,endMs,intervalMs}}`; choose exactly one selector, at most48samples | `frames[]` with requested/decoded time, source PTS, dimensions and URL; optional `contactSheet` with individual frame links; source metadata. |\n| `detect_scenes` / `media.detectScenes` | `{url}` | `scenes[]` with start/end milliseconds, frame indexes, source PTS; no split MP4 exports. |\n| `read_image_text` / `media.readImageText` | `{url}` | `regions[]` with text/rawText, polygons/boxes/confidence; inferred `lines[]`/reading order; `previewUrl`. |\n| `read_video_text` / `media.readVideoText` | `{url,mode:\"fast\",intervalMs:1000,range?:{startMs,endMs}}` OR `{url,mode:\"frame_scan\",range?:{startMs,endMs}}` | `frames[]`, text `tracks[]` with observations/positions; explicit `coverage.inspected` and `uninspected`. Maximum240inspected frames and120seconds per request. `intervalMs` only applies to fast mode. |\n| `transcribe_audio` / `media.transcribeAudio` | `{url,range?:{startMs,endMs},language?:\"auto\",timing?:\"word\",channel?:0}` | `status`, `text`, timed `segments[]` and estimated words, warnings, `audioPreviewUrl`. Range at most120seconds; timing `word` or `segment`; optional channel0/1. Empty/no-audio/no-speech states are distinct. |\n| `measure_audio_levels` / `media.measureAudioLevels` | `{url,range?:{startMs,endMs},windowMs?:100,silenceThresholdDbfs?:-50}` | Native-channel RMS/sample peaks, loudness timeline/LUFS, silence, possible clipping, `previewUrl`. Windows20–5000ms, threshold−100to−10dBFS, range at most120seconds. |\n| `sample_colors` / `media.sampleColors` | `{url,maxColors?:8,point?:{x,y},box?:{x,y,width,height},mask?}`; choose at most one selection | Observed RGBA point or palette/proportions, omitted mass, declared color policy, `previewUrl`. Palette1–32colors. |\n| `measure_layout` / `media.measureLayout` | `{url,elements:[{id,box:{x,y,width,height}}]}`; each element may instead have `mask` | Margins, centers, spacing/alignment deltas, intersections/IoU and `previewUrl`.1–32unique IDs. Boxes are supplied, not automatically detected. |\n| `match_text_style` / `media.matchTextStyle` | `{url,box:{x,y,width,height},text?}`; integer crop16–1536wide,16–512high; optional supplied text | `status`, candidates with real image-editor `element`/`previewConfig`, `maskIoU`, `foregroundMae`, `quality`, previews/comparison and warnings. Up to160printable ASCII characters/four lines; supported fonts Arial/TikTok/Apple. Missing/unsupported styles may be unavailable or approximations. |\n| `get_media_analysis` / `media.getMediaAnalysis` | `{jobId}` | Current status/result in the current organization; use when automatic waiting returned pending/processing. |\n\nBoxes are half-open source-pixel rectangles. For masks used by colors/layout:\n`{width,height,counts}` uses row-major binary RLE, alternating background then\nforeground. Counts must sum to width×height. This is not COCO's column-major\nconvention. Supply only masks you actually have; automatic segmentation is off.\n\n## Existing media library\n\n- `list_media({ids?,tag?})`, `list_social_audio({ids?,tag?})`.\n- `create_media_from_urls({urls,names?,tag?,sourceIds?,useName?})` registers URLs;\n  it does not turn an inaccessible local file into a public upload.\n- `import_text({texts:[{content,name?,tag?}]})`.\n- `create_social_audio({url,tag?})` imports social audio separately; do not use it\n  as proof of the exact soundtrack/mix/offset in a downloaded reference video.\n- `delete_media({ids})` removes media/storage; only use when deletion is requested.\n",
+    "content-automation/SKILL.md": "---\nname: content-automation\ndescription: Turn reference social posts or a rough content idea into a reusable UGC Inc workflow, with editable inputs and reviewed visual/audio output. Use for developing and validating content formats rather than scheduling existing finished posts.\nallowed-tools: Bash, Read\n---\n\nBuild the format the user wants and collaborate at the level they requested.\nWhen they want to discuss, compare or review a specific artifact, do that before\nmaking additional format decisions. Keep questions concise and ask only when a\nmissing answer prevents useful work. Do not impose a new per-video reference input\nwhen the user wants a fixed reusable visual format.\n\nUse the `media` skill for acquisition/inspection and the `automations` skill for\ncurrent workflow tool calls. Read [references/build-review.md](references/build-review.md)\nwhen constructing or reviewing a workflow. Use only shipped tools/nodes discovered\nthrough `npx ugcinc --list`, `list_node_types` and `get_node_type`.\n\n## Understand and specify the format\n\nAcquire a bounded set of real references and inspect full frames and changes over\ntime, including audio using available modalities. A contact sheet or transcript\nalone cannot establish all animation/pacing/music details. State uninspected\nparts instead of claiming playback. Distinguish reusable formats from variants;\nseveral posts may use the same structure with different assets, copy or timing.\n\nWrite a compact spec: what the viewer sees first, the sequence/reveal, required\ninputs, reusable assets/components, changing copy, audio source/timing and final\naction/CTA if required by this format. Separate measured facts from inference\nand user choices. Share a verified HTTPS reference/preview when the user needs\nto identify the parts they want changed.\n\nClassify assets by replacement behavior. A recognizable Mii, Wojak or other exact\nmeme image may need a static asset; an ordinary or newly generated face need not\nbe static just because it looks meme-like. Preserve a headshot's identity across\nvariants when requested, while making intended differences visibly meaningful.\n\n## Build reusable production behavior\n\nSeparate layout, data/assets and motion. Expose the inputs a normal run needs:\nasset pools/overrides, text pools, contact/destination, duration/timing and seed\nwhere appropriate. Keep canonical outputs independent of an operator's laptop.\nImplement procedural animations as reusable components rendered on demand;\ndo not substitute one pre-rendered clip when each run should vary. Randomness\nmust respect the intended visual roles and remain replayable from saved inputs.\n\nReuse existing nodes/compositions and actual public schemas. Analysis tools are\navailable as CLI/SDK operations; do not assume every one is a workflow node.\nValidate the graph before executing. Prefer a reviewable output over publishing\nor enabling recurring runs unless the user authorized those actions.\n\n## Make the content work\n\n- Keep the hierarchy clear: readable hook, focal content, then the intended CTA.\n  Give characters/subjects enough visual weight; align visible content within\n  its section instead of trusting transparent image bounds alone.\n- Measure margins, spacing, text wrapping and overlap. Check at phone viewing\n  size, not only on a large canvas. Keep important text away from platform UI;\n  inspect the relevant target presentation rather than assuming universal margins.\n- Use sampled reference colors and real render previews. Judge font, stroke,\n  kerning, line height and emoji spacing together. Treat text-style fitting as a\n  measured candidate, not proof of an exact font or pixel-perfect output.\n- Match the reference post's actual audio excerpt, mix, start and duration when\n  requested. Preserve attribution separately. Empty transcription can mean music\n  or unrecognized speech, not silence. Keep visual reveals and audio timing coherent.\n- Keep required CTA/contact copy present and legible across every requested\n  variant. Use the user's actual destination/formatting, not a number copied from\n  an old example. Vary copy intentionally without altering the required action.\n- Test with real content and multiple asset/copy lengths. A composition that\n  works with one face or one short headline is not a validated reusable format.\n  Inspect early, changing and final states; a still cannot certify a full video.\n\n## Deliver and describe the boundary\n\nProvide the workflow, its normal inputs, replayable example parameters, verified\nHTTPS previews, and any observed visual/audio limits. For videos verify decoding,\nduration/dimensions/audio and byte-range playback; images need correct content\ntype and decoding. Do not use local/localhost/private URLs as deliverables.\n\nSAM and automatic segmentation/overlay tracking are deferred. Use supplied\nassets, user-supplied boxes/masks or honest visual analysis; do not claim recovered\nsource layers or automatic clean cutouts. If the runtime cannot inspect a media\nmodality, record that limit and do not certify the uninspected property.\n",
+    "content-automation/references/build-review.md": "# Construct and review a reusable workflow\n\n## Discover the real interface\n\n`npx ugcinc list_node_types '{}'` lists current node metadata.\nUse `get_node_type '{\"nodeType\":\"...\"}'` for the nodes you choose and read the\nbundled `automations` skill for current tool parameters. These tools still need\na configured CLI key even when their own operation is local.\n\nConnections live on the target node, not a separate edges array:\n\n```json\n{\n  \"nodes\": [\n    {\n      \"id\": \"target\",\n      \"type\": \"node-type-from-discovery\",\n      \"config\": {},\n      \"inputs\": {\n        \"actual-input-port\": {\n          \"sourceNodeId\": \"source\",\n          \"sourceOutputId\": \"actual-output-port\"\n        }\n      }\n    }\n  ]\n}\n```\n\nUse actual IDs/configuration returned by discovery, not these placeholders.\nConfigure dynamic interfaces before wiring them. Re-check ports after config\nchanges. Current validation requires a terminal outcome; inspect pass-through,\nsave-to-media and posting nodes to choose the intended behavior. Publishing is\nnot required just to make a reviewable workflow output.\n\nFor reusable sub-workflows, configure their input/output contracts explicitly\nand inspect the Compose Workflow node's actual schema. For custom Remotion,\ninspect `remotion-composition`; use its supported composition/props/import\ncontract. Do not invent an upload/register API or rely on arbitrary packages.\n\nValidate using `validate_workflow` with the shape described by the installed\nautomation skill/tool. Execute only the intended single test scope, inspect its\nstatus/output, and retain resolved inputs and seed. Saving a template or receiving\na run ID alone does not prove the output renders correctly.\n\n## Review a representative run\n\nCheck the viewer's actual sequence: hook visibility, subject size, changing state,\ntext wrapping/CTA, transitions and finish. Compare the full frame before zooming\ninto details. Inspect multiple points around animation/text changes. Re-test a\nlonger caption and a different asset where those vary in normal runs.\n\nDistinguish observed pixels/timestamps from estimates. Examples: sRGB sampling\ndoes not recover design colors from compression, transcript word timestamps are\nestimated, sampled OCR leaves gaps, and bounding boxes are not exact ink bounds.\nManually supplied boxes are allowed; describe how they were determined.\n\nPreserve both soundtrack bytes and source attribution. Check whether music is\nembedded or only attributed, whether the output repeats/truncates it, and whether\nvisual changes coincide with the intended moments. Do not invent beat detection,\naudio separation, universal media comparison or other unavailable tools.\n\nWhen revising content, name the concrete issue and inspect the changed output.\nKeep reusable parameters instead of baking a correction into one reference\nimage. Report remaining defects plainly; avoid calling a draft production-ready\nbased only on successful API execution.\n"
+};

package/dist/skills.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skillFiles = void 0;
+const content_skills_1 = require("./content-skills");
 const run = 'npx ugcinc';
 exports.skillFiles = {
     'accounts/SKILL.md': `---
@@ -152,67 +153,6 @@ ${run} retry_posts '{"postIds":["id1"]}'
 - After creating a post, tell the user the post ID and scheduled time
 - For failed posts, check status first to understand the error before retrying
 - If $ARGUMENTS is provided, interpret it as a natural language request
-`,
-    'media/SKILL.md': `---
-name: media
-description: Manage UGC Inc media library - list, import, and organize videos, images, audio, and text. Use when the user wants to upload media, import audio, or manage their library.
-allowed-tools: Bash, Read
----
-
-You manage UGC Inc media through the CLI. Run tools with:
-\`\`\`bash
-${run} <tool_name> '<json_params>'
-\`\`\`
-
-Auth: \`npx ugcinc auth <api_key> [--admin]\`. Only needed once. Use \`--admin\` for admin keys.
-
-## Tools
-
-### list_media
-List all media (user media + social audio).
-\`\`\`bash
-${run} list_media
-${run} list_media '{"tag":"campaign-1"}'
-${run} list_media '{"ids":["id1","id2"]}'
-\`\`\`
-
-### list_social_audio
-List social audio only.
-\`\`\`bash
-${run} list_social_audio
-${run} list_social_audio '{"tag":"trending"}'
-\`\`\`
-
-### create_media_from_urls
-Import media from URLs (videos, images already hosted somewhere).
-\`\`\`bash
-${run} create_media_from_urls '{"urls":["https://example.com/video.mp4"],"tag":"imported"}'
-${run} create_media_from_urls '{"urls":["url1","url2"],"names":["Video 1","Video 2"]}'
-\`\`\`
-
-### import_text
-Import text content as media.
-\`\`\`bash
-${run} import_text '{"texts":[{"content":"Hello world","name":"greeting","tag":"captions"}]}'
-\`\`\`
-
-### create_social_audio
-Extract audio from a TikTok or Instagram URL.
-\`\`\`bash
-${run} create_social_audio '{"url":"https://www.tiktok.com/@user/video/123","tag":"trending"}'
-\`\`\`
-
-### delete_media
-Delete media items (also removes from storage).
-\`\`\`bash
-${run} delete_media '{"ids":["id1","id2"]}'
-\`\`\`
-
-## Workflow tips
-- Media types: video, image, audio, text, social_audio
-- When importing audio from TikTok/Instagram, use \`create_social_audio\` not \`create_media_from_urls\`
-- Tags help organize media - suggest tagging when importing
-- If $ARGUMENTS is provided, interpret it as a natural language request
 `,
     'automations/SKILL.md': `---
 name: automations
@@ -527,4 +467,5 @@ ${run} upsert_integration_key '{"provider":"openai","key":"sk-..."}'
 - Mention when stats were last refreshed and offer to refresh if stale
 - If $ARGUMENTS is provided, interpret it as a natural language request
 `,
+    ...content_skills_1.contentSkillFiles,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc",
-  "version": "4.26.0",
+  "version": "4.26.1",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,7 +23,7 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/build-skills.cjs && tsc",
     "prepublishOnly": "npm run build",
     "test": "echo \"No tests specified\" && exit 0"
   },
@@ -65,6 +65,7 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ]
 }

package/skills/content-automation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: content-automation
+description: Turn reference social posts or a rough content idea into a reusable UGC Inc workflow, with editable inputs and reviewed visual/audio output. Use for developing and validating content formats rather than scheduling existing finished posts.
+allowed-tools: Bash, Read
+---
+
+Build the format the user wants and collaborate at the level they requested.
+When they want to discuss, compare or review a specific artifact, do that before
+making additional format decisions. Keep questions concise and ask only when a
+missing answer prevents useful work. Do not impose a new per-video reference input
+when the user wants a fixed reusable visual format.
+
+Use the `media` skill for acquisition/inspection and the `automations` skill for
+current workflow tool calls. Read [references/build-review.md](references/build-review.md)
+when constructing or reviewing a workflow. Use only shipped tools/nodes discovered
+through `npx ugcinc --list`, `list_node_types` and `get_node_type`.
+
+## Understand and specify the format
+
+Acquire a bounded set of real references and inspect full frames and changes over
+time, including audio using available modalities. A contact sheet or transcript
+alone cannot establish all animation/pacing/music details. State uninspected
+parts instead of claiming playback. Distinguish reusable formats from variants;
+several posts may use the same structure with different assets, copy or timing.
+
+Write a compact spec: what the viewer sees first, the sequence/reveal, required
+inputs, reusable assets/components, changing copy, audio source/timing and final
+action/CTA if required by this format. Separate measured facts from inference
+and user choices. Share a verified HTTPS reference/preview when the user needs
+to identify the parts they want changed.
+
+Classify assets by replacement behavior. A recognizable Mii, Wojak or other exact
+meme image may need a static asset; an ordinary or newly generated face need not
+be static just because it looks meme-like. Preserve a headshot's identity across
+variants when requested, while making intended differences visibly meaningful.
+
+## Build reusable production behavior
+
+Separate layout, data/assets and motion. Expose the inputs a normal run needs:
+asset pools/overrides, text pools, contact/destination, duration/timing and seed
+where appropriate. Keep canonical outputs independent of an operator's laptop.
+Implement procedural animations as reusable components rendered on demand;
+do not substitute one pre-rendered clip when each run should vary. Randomness
+must respect the intended visual roles and remain replayable from saved inputs.
+
+Reuse existing nodes/compositions and actual public schemas. Analysis tools are
+available as CLI/SDK operations; do not assume every one is a workflow node.
+Validate the graph before executing. Prefer a reviewable output over publishing
+or enabling recurring runs unless the user authorized those actions.
+
+## Make the content work
+
+- Keep the hierarchy clear: readable hook, focal content, then the intended CTA.
+  Give characters/subjects enough visual weight; align visible content within
+  its section instead of trusting transparent image bounds alone.
+- Measure margins, spacing, text wrapping and overlap. Check at phone viewing
+  size, not only on a large canvas. Keep important text away from platform UI;
+  inspect the relevant target presentation rather than assuming universal margins.
+- Use sampled reference colors and real render previews. Judge font, stroke,
+  kerning, line height and emoji spacing together. Treat text-style fitting as a
+  measured candidate, not proof of an exact font or pixel-perfect output.
+- Match the reference post's actual audio excerpt, mix, start and duration when
+  requested. Preserve attribution separately. Empty transcription can mean music
+  or unrecognized speech, not silence. Keep visual reveals and audio timing coherent.
+- Keep required CTA/contact copy present and legible across every requested
+  variant. Use the user's actual destination/formatting, not a number copied from
+  an old example. Vary copy intentionally without altering the required action.
+- Test with real content and multiple asset/copy lengths. A composition that
+  works with one face or one short headline is not a validated reusable format.
+  Inspect early, changing and final states; a still cannot certify a full video.
+
+## Deliver and describe the boundary
+
+Provide the workflow, its normal inputs, replayable example parameters, verified
+HTTPS previews, and any observed visual/audio limits. For videos verify decoding,
+duration/dimensions/audio and byte-range playback; images need correct content
+type and decoding. Do not use local/localhost/private URLs as deliverables.
+
+SAM and automatic segmentation/overlay tracking are deferred. Use supplied
+assets, user-supplied boxes/masks or honest visual analysis; do not claim recovered
+source layers or automatic clean cutouts. If the runtime cannot inspect a media
+modality, record that limit and do not certify the uninspected property.

package/skills/content-automation/references/build-review.md

@@ -0,0 +1,66 @@
+# Construct and review a reusable workflow
+
+## Discover the real interface
+
+`npx ugcinc list_node_types '{}'` lists current node metadata.
+Use `get_node_type '{"nodeType":"..."}'` for the nodes you choose and read the
+bundled `automations` skill for current tool parameters. These tools still need
+a configured CLI key even when their own operation is local.
+
+Connections live on the target node, not a separate edges array:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "target",
+      "type": "node-type-from-discovery",
+      "config": {},
+      "inputs": {
+        "actual-input-port": {
+          "sourceNodeId": "source",
+          "sourceOutputId": "actual-output-port"
+        }
+      }
+    }
+  ]
+}
+```
+
+Use actual IDs/configuration returned by discovery, not these placeholders.
+Configure dynamic interfaces before wiring them. Re-check ports after config
+changes. Current validation requires a terminal outcome; inspect pass-through,
+save-to-media and posting nodes to choose the intended behavior. Publishing is
+not required just to make a reviewable workflow output.
+
+For reusable sub-workflows, configure their input/output contracts explicitly
+and inspect the Compose Workflow node's actual schema. For custom Remotion,
+inspect `remotion-composition`; use its supported composition/props/import
+contract. Do not invent an upload/register API or rely on arbitrary packages.
+
+Validate using `validate_workflow` with the shape described by the installed
+automation skill/tool. Execute only the intended single test scope, inspect its
+status/output, and retain resolved inputs and seed. Saving a template or receiving
+a run ID alone does not prove the output renders correctly.
+
+## Review a representative run
+
+Check the viewer's actual sequence: hook visibility, subject size, changing state,
+text wrapping/CTA, transitions and finish. Compare the full frame before zooming
+into details. Inspect multiple points around animation/text changes. Re-test a
+longer caption and a different asset where those vary in normal runs.
+
+Distinguish observed pixels/timestamps from estimates. Examples: sRGB sampling
+does not recover design colors from compression, transcript word timestamps are
+estimated, sampled OCR leaves gaps, and bounding boxes are not exact ink bounds.
+Manually supplied boxes are allowed; describe how they were determined.
+
+Preserve both soundtrack bytes and source attribution. Check whether music is
+embedded or only attributed, whether the output repeats/truncates it, and whether
+visual changes coincide with the intended moments. Do not invent beat detection,
+audio separation, universal media comparison or other unavailable tools.
+
+When revising content, name the concrete issue and inspect the changed output.
+Keep reusable parameters instead of baking a correction into one reference
+image. Report remaining defects plainly; avoid calling a draft production-ready
+based only on successful API execution.

package/skills/media/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: media
+description: Acquire TikTok and Instagram posts and inspect images, video and audio with UGC Inc tools. Use for reference analysis, OCR, frames, scenes, transcription, colors, layout, text-style fitting, or media-library management.
+allowed-tools: Bash, Read
+---
+
+Use the installed UGC Inc CLI:
+
+```bash
+npx ugcinc --list
+npx ugcinc <tool_name> '<json_params>'
+```
+
+Credentials come from `UGC_API_KEY` or existing UGC configuration. Use the user's
+organization and a key with `content:analyze` for acquisition/analysis. If using
+an admin key, pass the authorized `orgId` in the JSON parameters. Do not print
+credentials, copy an administrator key to another user's machine, or change
+organizations to bypass a denial. Confirm access with one small tool call.
+If credentials already live in an app env file, set `UGC_ENV_FILE` to that file's
+path so the CLI reads the existing key without duplicating its contents. Set
+`UGC_ORG_ID` in that file or the process environment to scope calls to the user's
+organization; an explicit JSON `orgId` takes priority.
+
+Read [references/tools.md](references/tools.md) for request shapes, result fields
+and limits. The CLI lists names/descriptions; the reference explains parameters.
+
+## Choose the input and tools
+
+- A profile URL: `list_profile_posts` discovers a bounded page; follow its cursor
+  only as needed. Listing does not download media or guarantee complete history.
+- A post URL: `download_social_post` ingests its ordered assets into owned media.
+  Use returned asset URLs for analysis; the TikTok/Instagram HTML URL is not a
+  video file. Check complete/partial/failed status and failed assets.
+- A direct media URL: use the corresponding inspection tool directly.
+- Video: `detect_scenes`, `extract_frames`, `read_video_text`; audio tools accept
+  video too. Inspect multiple moments, including changes near the beginning/end.
+- Image: `read_image_text`, `sample_colors`, `measure_layout` using supplied
+  boxes/masks, and `match_text_style` for a specified text crop.
+- Audio: `transcribe_audio` and `measure_audio_levels`.
+
+The SDK/CLI waits for processing automatically. Check both the outer response's
+`ok` and the returned job's `status`. Analysis is usable when
+`data.status === "completed"`; its content is `data.result`. If still pending or
+processing, keep its job ID and use `get_media_analysis` rather than resubmitting.
+Use bounded retries for retryable failures; report persistent errors/partial
+coverage. A zero process exit code alone does not establish API success.
+
+## Interpret evidence accurately
+
+- Coordinates are display-oriented source pixels; times are source-relative
+  milliseconds. Use returned decoded timestamps, dimensions and coverage.
+- OCR is English, may miss stylized text, and can be empty on unreadable input.
+  `fast` video OCR leaves uninspected intervals. `frame_scan` is bounded and
+  cannot inspect an arbitrarily long clip in one request.
+- Speech timestamps are estimates; speaker labels/forced alignment are absent.
+  A transcript does not establish music, emotion, delivery or sound effects.
+- Color sampling measures decoded sRGB pixels, not guaranteed design hex values.
+  Layout measurement does not detect objects or recover original layer files.
+- Text-style matching returns supported UGC settings and visual residuals. Font
+  identity is unverified; inspect the preview before calling a fit accurate.
+  It has a restricted ASCII/font/style surface; the native TikTok renderer is a
+  separate bounded rendering capability, not proof that matching is exact.
+- SAM/object segmentation, automatic overlay detection, element/mask tracking,
+  motion measurement, extraction, media comparison/alignment and semantic search
+  are not available through this tool set. Do not invent those calls or install
+  SAM. Existing OCR text tracks remain available.
+
+## Review and share media
+
+Open returned image/contact-sheet previews and review the relevant sequence.
+When the agent runtime can consume audio/video, use it. Otherwise use the
+available transcript, audio preview and level measurements and explicitly state
+what was not listened to or inspected. Do not claim to have watched/listened
+because an analysis request succeeded.
+
+Share only verified browser-accessible HTTPS artifacts. Fetch without auth and
+check status, content type and decoding; for video also check byte-range support.
+Use the returned owned-media URLs. Local paths, localhost/private addresses and
+expiring upstream CDN links are not deliverable previews. If an artifact needs
+uploading, use the supported owned storage path; do not claim a file is hosted
+because a media record was created for an arbitrary URL.
+
+For building a reusable content format, use the `content-automation` skill.

package/skills/media/references/tools.md

@@ -0,0 +1,64 @@
+# UGC media tool requests and results
+
+Run `npx ugcinc TOOL 'JSON'`. Shell quoting varies on Windows; if the shell
+changes the JSON, use a small Node script with `UGCClient` and its `media`
+methods instead of repeatedly sending malformed requests. For example:
+
+```js
+const { UGCClient } = require('ugcinc');
+const client = new UGCClient({
+  apiKey: process.env.UGC_API_KEY,
+  orgId: process.env.UGC_ORG_ID,
+});
+// Use admin:true only with an authorized administrator credential.
+```
+
+Request URLs must be HTTPS. Analysis source URLs must not contain credentials
+or fragments. Image operations support still PNG/JPEG/WebP, at most4096pixels
+per side; the shared download limit is100MiB. Geometry must fit the actual
+display-oriented source. Respect more restrictive operation limits below.
+
+## Acquisition
+
+| CLI tool / SDK method | Parameters | Result |
+| --- | --- | --- |
+| `list_profile_posts` / `media.listProfilePosts` | `{url, limit?, cursor?}`; TikTok/Instagram profile; limit1–50 | `data.posts`, profile metadata, continuation cursor. Follow the actual returned cursor, not a fabricated page number. |
+| `download_social_post` / `media.downloadSocialPost` | `{url}`; canonical TikTok/Instagram post URL | `data.status`, `assets[]` in order, `failedAssets[]`, `manifestUrl`, post/sound metadata. Each asset has `url`, `mediaId`, dimensions, type, duration, audio presence and hash. Repeat the same URL to resume retryable partial imports. |
+
+Embedded video audio remains attached. Photo assets have no embedded soundtrack;
+sound attribution does not mean audio bytes were downloaded. Preserve sound
+ID/link separately; never replace a post excerpt with the full sound-page track
+and call them identical. Partial imports are not a complete carousel.
+
+## Analysis
+
+These return `{ok, data:{jobId,status,operation,result?,error?}}`. Use the completed
+`data.result` fields listed below. Failure can occur after successful submission.
+
+| CLI tool / SDK method | Parameters | Result content |
+| --- | --- | --- |
+| `extract_frames` / `media.extractFrames` | `{url,timestampsMs:[0,1500,3000],selection:"nearest",contactSheet:true}` OR `{url,range:{startMs,endMs,intervalMs}}`; choose exactly one selector, at most48samples | `frames[]` with requested/decoded time, source PTS, dimensions and URL; optional `contactSheet` with individual frame links; source metadata. |
+| `detect_scenes` / `media.detectScenes` | `{url}` | `scenes[]` with start/end milliseconds, frame indexes, source PTS; no split MP4 exports. |
+| `read_image_text` / `media.readImageText` | `{url}` | `regions[]` with text/rawText, polygons/boxes/confidence; inferred `lines[]`/reading order; `previewUrl`. |
+| `read_video_text` / `media.readVideoText` | `{url,mode:"fast",intervalMs:1000,range?:{startMs,endMs}}` OR `{url,mode:"frame_scan",range?:{startMs,endMs}}` | `frames[]`, text `tracks[]` with observations/positions; explicit `coverage.inspected` and `uninspected`. Maximum240inspected frames and120seconds per request. `intervalMs` only applies to fast mode. |
+| `transcribe_audio` / `media.transcribeAudio` | `{url,range?:{startMs,endMs},language?:"auto",timing?:"word",channel?:0}` | `status`, `text`, timed `segments[]` and estimated words, warnings, `audioPreviewUrl`. Range at most120seconds; timing `word` or `segment`; optional channel0/1. Empty/no-audio/no-speech states are distinct. |
+| `measure_audio_levels` / `media.measureAudioLevels` | `{url,range?:{startMs,endMs},windowMs?:100,silenceThresholdDbfs?:-50}` | Native-channel RMS/sample peaks, loudness timeline/LUFS, silence, possible clipping, `previewUrl`. Windows20–5000ms, threshold−100to−10dBFS, range at most120seconds. |
+| `sample_colors` / `media.sampleColors` | `{url,maxColors?:8,point?:{x,y},box?:{x,y,width,height},mask?}`; choose at most one selection | Observed RGBA point or palette/proportions, omitted mass, declared color policy, `previewUrl`. Palette1–32colors. |
+| `measure_layout` / `media.measureLayout` | `{url,elements:[{id,box:{x,y,width,height}}]}`; each element may instead have `mask` | Margins, centers, spacing/alignment deltas, intersections/IoU and `previewUrl`.1–32unique IDs. Boxes are supplied, not automatically detected. |
+| `match_text_style` / `media.matchTextStyle` | `{url,box:{x,y,width,height},text?}`; integer crop16–1536wide,16–512high; optional supplied text | `status`, candidates with real image-editor `element`/`previewConfig`, `maskIoU`, `foregroundMae`, `quality`, previews/comparison and warnings. Up to160printable ASCII characters/four lines; supported fonts Arial/TikTok/Apple. Missing/unsupported styles may be unavailable or approximations. |
+| `get_media_analysis` / `media.getMediaAnalysis` | `{jobId}` | Current status/result in the current organization; use when automatic waiting returned pending/processing. |
+
+Boxes are half-open source-pixel rectangles. For masks used by colors/layout:
+`{width,height,counts}` uses row-major binary RLE, alternating background then
+foreground. Counts must sum to width×height. This is not COCO's column-major
+convention. Supply only masks you actually have; automatic segmentation is off.
+
+## Existing media library
+
+- `list_media({ids?,tag?})`, `list_social_audio({ids?,tag?})`.
+- `create_media_from_urls({urls,names?,tag?,sourceIds?,useName?})` registers URLs;
+  it does not turn an inaccessible local file into a public upload.
+- `import_text({texts:[{content,name?,tag?}]})`.
+- `create_social_audio({url,tag?})` imports social audio separately; do not use it
+  as proof of the exact soundtrack/mix/offset in a downloaded reference video.
+- `delete_media({ids})` removes media/storage; only use when deletion is requested.