ugcinc 4.26.0 → 4.27.0

package/README.md

@@ -357,6 +357,195 @@ Both operations require an organization and `content:analyze` for scoped keys.
 Errors may include `errorCode` and `retryable`. Existing scraper credit/rate safeguards
 apply. Storage/provider errors do not imply that a post or profile was deleted.
 
+## Native iMessage conversations and PNG snapshots (staged)
+
+The native conversation API is implemented behind a rollout gate and is **not yet
+enabled on the public service**. Until rollout, submission returns a retryable 503.
+The existing still-image DM renderer remains available separately.
+
+Quick reference: `client.media.renderIMessageConversation(input)` queues a video by default;
+`client.media.getIMessageConversation({jobId})` polls its status.
+`client.media.cancelIMessageConversation({jobId})` requests cancellation and native cleanup.
+`compileIMessageConversation(input)` previews its deterministic timing plan locally.
+
+```ts
+import {UGCClient, compileIMessageConversation, type IMessageConversationInput} from 'ugcinc';
+
+const client = new UGCClient({apiKey: 'YOUR_API_KEY', orgId: 'YOUR_ORG_ID'});
+const input = {
+  idempotencyKey: 'conversation-v1',
+  contact: {name: 'Alex'},
+  theme: 'dark',
+  statusBar: {time: '12:34', wifiBars: 3, cellularBars: 4, batteryPercent: 85},
+  unreadCount: 12,
+  timestampText: 'Today 12:34 PM',
+  seed: 42,
+  timing: {charactersPerSecond: 7, pauseBeforeMs: 500, pauseBeforeSendMs: 200, incomingTypingDurationMs: 2400},
+  messages: [
+    {sender: 'recipient', text: 'Ready?', initial: true},
+    {sender: 'user', text: 'On my way 👋'},
+    {sender: 'recipient', text: 'See you soon!', timing: {incomingTypingDurationMs: 3200}},
+  ],
+} satisfies IMessageConversationInput;
+const plan = compileIMessageConversation(input);
+const submitted = await client.media.renderIMessageConversation(input);
+if (submitted.ok) {
+  const status = await client.media.getIMessageConversation({jobId: submitted.data.jobId});
+  if (status.ok && status.data.status === 'completed') console.log(status.data.url);
+}
+// A lossless frame from the same native scene. Omit atMs for its final frame.
+const still = await client.media.renderIMessageConversation({
+  ...input, idempotencyKey: 'conversation-png-v1', output: {kind: 'png', atMs: 500},
+});
+```
+
+API reference:
+
+- `POST /media/render/imessage`: authenticated organization-scoped submission.
+- `POST /media/render/imessage/status`: `{jobId}`; only jobs owned by that
+  organization can be queried.
+- `POST /media/render/imessage/cancel`: `{jobId}`; requests cancellation for an
+  owned job. Poll status until `cancelled` or another terminal status. A pending
+  request returns `cancelRequested: true`; it does not claim native cleanup has
+  finished. Completed jobs retain their result if cancellation arrives too late.
+  Scoped keys need `content:render` for all three routes.
+- These return the normal `ApiResponse`. Job data includes `jobId`,
+  `status: pending | processing | completed | failed | cancelled`, `progress`, `fps: 60`,
+  `durationMs` (planned timeline duration) and `durationInFrames`. Completed jobs
+  include an owned HTTPS `url`, `output` settings and `contentType` (`video/mp4`
+  or `image/png`). Failed jobs include a safe error and retryability.
+  Submission does not wait for completion.
+- Output uses the pinned `iphone-xs-ios18.6.2` UI, native text/emoji and native
+  conversation motion. Video is 60fps H264; it is not frame-interpolated.
+  Native frames are 1125×2436; MP4 adds one background-colored column for an
+  even 1126-pixel codec width. This profile does not represent newer iOS designs.
+- `output` defaults to `{kind: 'video'}`. `{kind: 'png', atMs: 500}` returns the
+  original 1125×2436 native full-frame PNG bytes at that exact millisecond timestamp;
+  omitting `atMs` selects the final authored frame. Times outside the planned
+  conversation reject. PNG uses the same native scene and transitions, with no
+  resizing, separate text renderer or lossy video-frame extraction. For PNG jobs,
+  `durationInFrames` is 1 while `durationMs` still describes the authored timeline;
+  the renderer completes outstanding native actions privately for clean teardown.
+- `contact.name` is the other person's display name/username. Optional
+  `contact.avatarPngBase64` is a PNG without a data-URL prefix, at most 512×512
+  and 65536 base64 characters; the native ContactsUI component crops it. It is
+  an in-memory render input and does not create or save a real contact.
+- `statusBar` supports `time` (H:mm/HH:mm, default `9:41`), `wifiBars` (0–3,
+  default 3), `cellularBars` (0–4, default 4), `wifiEnabled`/`cellularEnabled`
+  (default true), `batteryPercent` (0–100, default 100), `charging` and
+  `lowPowerMode` (default false). Capacity controls the native battery fill;
+  it does not turn on a numerical percentage label. These configure render
+  models, not the host phone's clock, network or battery settings.
+- `unreadCount` (0–9999, default 0) controls the native back-button badge.
+  The number of conversation messages is simply `messages.length`; there is
+  no second message-count field to keep in sync. Optional `timestampText`
+  replaces native date-header text, independently of the status-bar clock.
+- Provide `contact: {name}` or `group` (described below). `theme` defaults to `dark`, `keyboard` to `true`,
+  `fps` to `60` (the only supported rate), `seed` to `0`, and `endHoldMs` to `1500`
+  (350–10000). `showIncomingTyping` defaults to `true`.
+- Messages require a `sender` ID (`user | recipient` for direct chats, or a group participant ID) and either nonempty `text` (up to 2000
+  UTF-16 code units) or `imagePngBase64`. Image captions and mixed text/image
+  messages are rejected. An image must be a single-frame PNG, without a data URL
+  prefix, at most 2048×2048 and 8 MiB of base64 characters. The full request is
+  limited to 16 MiB; aggregate message image dimensions cannot exceed 16,777,216
+  pixels. Outgoing images enter the native composer before send; the plan reserves
+  its native attachment transition plus `pauseBeforeSendMs`. Initial and incoming
+  images do not open the local composer. `user` is outgoing. Optional IDs must be unique; otherwise
+  IDs are generated. `initial: true` supplies preexisting history and must be a
+  prefix. Incoming messages may override `showTyping`; their text is hidden
+  until arrival. Outgoing text appears in the composer.
+- Outgoing messages accept `receipt: none | delivered | read` (default `none`).
+  Read state requires `readAt`, an ISO timestamp with timezone. Animated receipts
+  appear `receiptDelayMs` after arrival (0–30000, default 500); history receipts
+  are present initially. As in Messages, the visible receipt belongs to the
+  latest outgoing message; older receipts disappear when a newer one is sent.
+  Delayed receipts extend the render duration so they are not truncated.
+- Default `timing`: `charactersPerSecond: 8` (0.5–60), `pauseBeforeMs: 450`
+  (0–30000), `pauseBeforeSendMs: 180` (0–10000), `punctuationPauseMs: 160`
+  (0–2000), `variation: 0.15` (0–0.75). Each message can override any setting.
+  Pauses use milliseconds. Typing speed counts complete visible grapheme clusters,
+  including a whole family emoji or combining-accent sequence as one character.
+  Variation uses the supplied seed. The plan reserves native transition completion
+  before starting the next message, then applies `pauseBeforeMs` before typing.
+- Outgoing emoji input is represented explicitly in the authoring timeline:
+  open the native emoji keyboard, focus an emoji, select it, then return to the
+  letter keyboard when subsequent text needs it. `timing.keyboardSwitchPauseMs`
+  (350–10000, default 450) controls the pause after switching keyboards;
+  `timing.emojiSelectionDelayMs` (100–10000, default 350) controls the pause before
+  selecting a focused emoji. These can be overridden per message. Complete
+  grapheme sequences are preserved. Incoming emoji text never opens the local
+  keyboard. Outgoing emoji interactions require `keyboard: true`. Emoji that require
+  an unsupported long-press skin-tone or family picker reject instead of being
+  inserted through an invisible shortcut.
+- Optional `timing.incomingTypingDurationMs` (0–30000) sets the exact interval
+  from the other person's typing indicator starting until their message arrives.
+  Set it globally or override it in an incoming message's `timing` (for example
+  2400 globally and 3200 for a longer reply). `pauseBeforeMs` still controls when
+  typing starts. This replaces the incoming duration calculated from character
+  speed, punctuation and the pre-send pause; outgoing composer speed is unchanged.
+  Omit it to retain the calculated duration. Zero is supported. With
+  `showTyping: false`, the same response delay applies without a visible indicator.
+  Setting this field on an outgoing message rejects.
+- `replyTo` on a message names an earlier message ID. Native thread identity,
+  quoted context and reply grouping are derived on the render host. Replies to
+  replies remain in their original thread, while the visible reply gesture targets
+  the exact message named by `replyTo`. For an animated local reply, the compiler
+  emits `reply.begin`, long-presses that message, opens its native menu, selects
+  **Reply**, and waits for the reply view before typing and sending inside it.
+  It emits `reply.end` after sending and closes the
+  reply view before the next local action. `pauseBeforeMs` occurs before the
+  gesture; the compiled `typingStartMs` records when typing actually starts after
+  the opening transition. Incoming replies and initial history show their reply
+  associations without operating the local reply controls. Animated local replies
+  require `keyboard: true`; incoming replies and history also work without it.
+- Use `contact` for a direct chat, or `group: {name, localParticipantId,
+  participants: [{id, name}]}` for a group. Provide exactly one. A group has
+  3–20 participants including the local participant; IDs are unique. Message
+  `sender` and reaction `actor` use those IDs. For direct chats they remain
+  `user` and `recipient`. Group names, sender labels, avatars and bubble
+  grouping use the native group conversation UI. Optional `group.avatarPngBase64`
+  and `participants[].avatarPngBase64` accept the same bounded PNG format as
+  `contact.avatarPngBase64`.
+- `statusBar.time` controls only the clock. Top-level `timestampText` controls
+  the first conversation separator independently. Optional message `sentAt`
+  sets the actual conversation date (ISO 8601 with timezone); provide it for
+  every message in chronological order when used. Native date-gap rules create
+  later separators. A message's optional `timestampText` forces a separator
+  before it and sets its displayed text, such as `Today 3:10 PM`. These dates
+  do not affect typing speed or make the rendered video wait through the gap.
+- A message's optional `reactions` array schedules reactions relative to that
+  message's arrival (or video start for initial history). Each entry takes an
+  `actor`, `delayMs` (0–60000, default 700), and either a classic `reaction:
+  love | like | dislike | laugh | emphasize | question` or one `emoji`.
+  Local actions open the native reaction picker, hold it for `menuDurationMs`
+  (400–10000, default 700), then select the reaction. They reserve the local
+  interaction timeline until dismissal completes before further typing or
+  another local reaction. `delayMs` is the earliest picker-open time for local
+  actions, and the arrival time for remote reactions. Remote reactions do not
+  show a local picker. Custom emoji currently work for remote participants;
+  local actions accept the six classic picker options. `action: remove`
+  selects the actor's current reaction again through the picker, and takes no
+  reaction/emoji value. Setting again replaces the actor's previous reaction.
+  At most 20 reaction events per message are accepted.
+- Optional `threads: [{messageId, openAtMs, durationMs}]` opens and closes the
+  native expanded reply view for reading. These explicit thread views run after
+  the conversation and its native transitions settle; typing/sending during
+  these read-only views is not supported. Animated local `replyTo` messages use
+  their own reply-composition flow described above. Duration is 600–30000ms, at most ten views, without
+  overlap. The original conversation returns when the view closes.
+- Maximum 30 messages, 6000 animated visible characters and a planned duration of
+  120 seconds. Invalid or excessive requests reject before device use. The local
+  compiler exposes message arrival times, events and frame count.
+- Optional `idempotencyKey` (1–128 characters) deduplicates submissions within an
+  organization. Reuse the same body/key to recover the same job; changing the body
+  returns 409. To retry a failed render, use a new key or omit it. Job ownership
+  records are retained for seven days.
+- This authoring API currently supports text/emoji, initial history and sequential
+  conversations with configurable chrome, receipts, reactions and replies. Image attachments,
+  carrier-name/network-type selection, numerical
+  battery-percentage display and arbitrary timeline seeking are not accepted
+  by this contract. Unknown input fields reject rather than silently approximating them.
+
 ## Video inspection
 
 ```ts
@@ -484,3 +673,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/automations/nodes/create-dm.d.ts

@@ -1,4 +1,5 @@
-import type { ImageValue, TextValue, BooleanValue } from '../types';
+import type { ImageValue, VideoValue, TextValue, BooleanValue } from '../types';
+import type { IMessageConversationInput } from '../../imessage-conversation';
 import { type InputType, type OutputMode, type SelectionMode } from './types';
 /** Create DM message structure */
 export interface CreateDmMessage {
@@ -8,6 +9,7 @@ export interface CreateDmMessage {
 }
 /** Create DM inputs - optional based on inputType settings */
 export interface CreateDmNodeInputs {
+    conversation?: IMessageConversationInput;
     platform?: TextValue;
     'light-mode'?: BooleanValue;
     username?: TextValue;
@@ -21,12 +23,15 @@ export interface CreateDmNodeInputs {
 }
 /** Create DM has a fixed 'output' port. */
 export interface CreateDmNodeOutputs {
-    output: ImageValue;
+    output: ImageValue | VideoValue;
 }
 export type DmPlatform = 'imessage' | 'instagram';
 declare const definition: import("./types").NodeDefinition<"create-dm", "generator", {
     platform: DmPlatform;
     platformInputType: InputType;
+    imessageRenderMode: "still" | "conversation";
+    imessageConversationInputType: InputType;
+    imessageConversation: IMessageConversationInput | undefined;
     lightMode: boolean;
     lightModeInputType: InputType;
     username: string;

package/dist/automations/nodes/create-dm.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const imessage_conversation_1 = require("../../imessage-conversation");
 const types_1 = require("./types");
 // =============================================================================
 // Node Definition
@@ -7,8 +8,8 @@ const types_1 = require("./types");
 const definition = (0, types_1.defineNode)({
     nodeId: 'create-dm',
     label: 'Create DM',
-    description: 'Create fake DM screenshots for iMessage or Instagram',
-    guide: 'Renders realistic DM/conversation screenshots (iMessage or Instagram). Best for videos that simulate a conversation—e.g. rizz help, dating advice, or "what would you reply" style content. Use cases: rizz help videos, conversation simulations, dating advice content. Configure platform, light/dark mode, messages, profile pic. Messages can be static or variable (from LLM). Output is an image for Image Composer or Auto Post. Supports dynamic crop to isolate specific messages.',
+    description: 'Create DM screenshots or native iMessage videos and snapshots',
+    guide: 'Still mode renders legacy iMessage or Instagram screenshots with optional dynamic cropping. Conversation mode renders a native 60fps iMessage video with visible outgoing typing, incoming typing indicators, replies, reactions, receipts and group participants. Set imessageRenderMode to conversation and provide imessageConversation using the public IMessageConversationInput schema; alternatively connect the conversation object input. Native output defaults to video; output {kind: png, atMs: 500} exports a lossless native frame at 500ms, or omit atMs for the final frame. Static native PNG settings expose an image port; dynamic conversation inputs expose image|video. It requires platform imessage with static platform selection. Legacy still mode remains unchanged.',
     type: 'generator',
     category: 'Generation',
     outputModes: ['per-input', 'single'],
@@ -16,6 +17,9 @@ const definition = (0, types_1.defineNode)({
     defaults: {
         platform: 'instagram',
         platformInputType: 'static',
+        imessageRenderMode: 'still',
+        imessageConversationInputType: 'static',
+        imessageConversation: undefined,
         lightMode: true,
         lightModeInputType: 'static',
         username: '',
@@ -48,7 +52,27 @@ const definition = (0, types_1.defineNode)({
         outputMode: 'per-input',
         selectionMode: null,
     },
+    validate: config => {
+        if (config.imessageRenderMode !== 'conversation')
+            return [];
+        if (config.platform !== 'imessage' || config.platformInputType === 'variable') {
+            return ['Conversation video mode requires iMessage with static platform selection.'];
+        }
+        if (config.imessageConversationInputType === 'variable')
+            return [];
+        const parsed = imessage_conversation_1.iMessageConversationSchema.safeParse(config.imessageConversation);
+        return parsed.success ? [] : parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`);
+    },
     computePorts: ({ config }) => {
+        if (config?.imessageRenderMode === 'conversation') {
+            return {
+                inputs: config.imessageConversationInputType === 'variable'
+                    ? [{ id: 'conversation', type: 'object', isArray: false, required: true }]
+                    : [],
+                outputs: [{ id: 'output', type: config.imessageConversationInputType === 'variable' ? ['image', 'video']
+                            : config.imessageConversation?.output?.kind === 'png' ? 'image' : 'video', isArray: false, required: true }],
+            };
+        }
         const inputs = [];
         if (config?.platformInputType === 'variable') {
             inputs.push({ id: 'platform', type: 'text', isArray: false, required: true });

package/dist/automations/nodes/index.d.ts

@@ -101,6 +101,9 @@ export declare const nodeDefinitions: {
     readonly 'create-dm': NodeDefinition<"create-dm", "generator", {
         platform: import("./create-dm").DmPlatform;
         platformInputType: import("./types").InputType;
+        imessageRenderMode: "still" | "conversation";
+        imessageConversationInputType: import("./types").InputType;
+        imessageConversation: import("../..").IMessageConversationInput | undefined;
         lightMode: boolean;
         lightModeInputType: import("./types").InputType;
         username: string;
@@ -333,6 +336,8 @@ export declare const nodeDefinitions: {
         __TOutputs: import("./screenshot-animation").ScreenshotAnimationNodeOutputs;
     };
     readonly 'remotion-composition': NodeDefinition<"remotion-composition", "generator", {
+        fps: number;
+        durationInFrames: number;
         width: number;
         height: number;
         source: string;
@@ -340,13 +345,11 @@ export declare const nodeDefinitions: {
         selectionMode: null;
         outputType: "video" | "image";
         inputs: {
-            type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+            type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
             id: string;
             isArray: boolean;
             required: boolean;
         }[];
-        fps: number;
-        durationInFrames: number;
         inputProps: Record<string, unknown>;
     }, {
         [x: string]: import("../types").PortValue | import("../types").PortValue[];

package/dist/automations/nodes/remotion-composition.d.ts

@@ -4,6 +4,8 @@ type Outputs = {
     output: VideoValue;
 };
 declare const defaults: {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
@@ -11,16 +13,16 @@ declare const defaults: {
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 };
 declare const _default: import("./types").NodeDefinition<"remotion-composition", "generator", {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
@@ -28,13 +30,11 @@ declare const _default: import("./types").NodeDefinition<"remotion-composition",
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 }, Inputs, Outputs, false> & {
     __TInputs: Inputs;

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"
+};