@clipit-ai/cli 0.2.3 → 0.2.4

package/bin/clipit.mjs

@@ -9,7 +9,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-const VERSION = '0.2.3';
+const VERSION = '0.2.4';
 const DEFAULT_BASE_URL = 'https://clipit.dev';
 const DEFAULT_SCOPES = [
   'clippy_agent',
@@ -30,6 +30,8 @@ const RETRY_AFTER_CAP_MS = 10_000;
 const RETRYABLE_GET_STATUSES = new Set([429, 502, 503, 504]);
 const RECENT_LIMIT = 20;
 const REMOTION_ESTIMATED_USD_PER_VIDEO_SECOND = 0.0015;
+const BYTES_PER_GB = 1024 * 1024 * 1024;
+const DIRECT_VIDEO_UPLOAD_MAX_BYTES = readPositiveIntegerEnv('CLIPIT_CLI_DIRECT_UPLOAD_MAX_BYTES', 100 * 1024 * 1024);
 const MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
   'exports start': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
   'thumbnails generate': [{ operationType: 'thumbnail_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'one-generation' }],
@@ -38,12 +40,151 @@ const MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
     { operationType: 'image_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'broll-images' },
     { operationType: 'video_generation', provider: 'replicate', modelId: 'alibaba/happyhorse-1.0', metrics: 'broll-video' },
   ],
+  'clips create': [{ operationType: 'clip', provider: 'deepgram', metrics: 'clip-create' }],
   'clips render': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
+  'videos upload': [{ operationType: 'video_storage', provider: 'railway_s3', metrics: 'video-upload-storage' }],
   'videos import-url': [{ operationType: null, provider: null, metrics: 'url-import' }],
+  'videos transcribe': [{ operationType: 'transcription', provider: 'deepgram', modelId: 'nova-3', metrics: 'transcription-video' }],
+  'videos suggest-clips': [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'x-ai/grok-4.20-beta', metrics: 'suggest-clips' }],
   'social post': [{ operationType: 'social_post', provider: 'zernio', metrics: 'social-platforms' }],
   'social schedule': [{ operationType: 'social_post', provider: 'zernio', metrics: 'social-platforms' }],
 });
 
+const REMOTION_RUN_ESTIMATE = MAX_CREDITS_ESTIMATE_MAP['clips render'];
+
+const RUN_MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
+  planBRoll: MAX_CREDITS_ESTIMATE_MAP['broll plan'],
+  createThumbnail: MAX_CREDITS_ESTIMATE_MAP['thumbnails generate'],
+  generateThumbnails: MAX_CREDITS_ESTIMATE_MAP['thumbnails generate'],
+  generateImage: [{ operationType: 'image_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'one-generation' }],
+  generateBRoll: MAX_CREDITS_ESTIMATE_MAP['broll generate'],
+  generateVoiceover: [{ operationType: 'tts_generation', provider: 'replicate', modelId: 'google/gemini-3.1-flash-tts', metrics: 'tts-provider-cost' }],
+  generateMusicBed: [{ operationType: 'music_generation', provider: 'replicate', modelId: 'minimax/music-2.5', metrics: 'one-generation' }],
+  generateVideoAlter: [{ operationType: 'video_alter_generation', provider: 'replicate', modelId: 'kwaivgi/kling-v3-omni-video', metrics: 'video-alter-provider-cost' }],
+  generatePlatformCaption: [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'anthropic/claude-opus-4.7', metrics: 'platform-caption' }],
+  applyHookToFront: REMOTION_RUN_ESTIMATE,
+  addLibraryAssetToClip: REMOTION_RUN_ESTIMATE,
+  renderClipWithRemotion: REMOTION_RUN_ESTIMATE,
+  updateClipBounds: REMOTION_RUN_ESTIMATE,
+  setCropPosition: REMOTION_RUN_ESTIMATE,
+  applyRemotionCaptionPreset: REMOTION_RUN_ESTIMATE,
+  setCaptionAnimation: REMOTION_RUN_ESTIMATE,
+  setClipAspectRatio: REMOTION_RUN_ESTIMATE,
+  setCropLayout: REMOTION_RUN_ESTIMATE,
+  setTimedCropLayouts: REMOTION_RUN_ESTIMATE,
+  applyCropPreset: REMOTION_RUN_ESTIMATE,
+  setWatermark: REMOTION_RUN_ESTIMATE,
+  applyTextOverlayToClip: REMOTION_RUN_ESTIMATE,
+  applyBRoll: REMOTION_RUN_ESTIMATE,
+  removeBRoll: REMOTION_RUN_ESTIMATE,
+});
+
+const RUN_CONFIRMATION_LABELS = Object.freeze({
+  renderClipWithRemotion: 'Rendering a clip',
+});
+
+const RUN_METERED_CONFIRMATION_EXEMPTIONS = new Set([
+  'planBRoll',
+  'planVideoAlter',
+  'planVoiceover',
+  'planMusicBed',
+]);
+
+const CLIP_IDS_CONTEXT_TOOLS = new Set([
+  'runDeliveryReadinessQA',
+  'runBlueprintExportQA',
+]);
+
+const BILLING_PROVIDER_PREFERENCES = new Set(['x402_direct', 'stripe_mpp', 'stripe_x402']);
+
+const LOCAL_MCP_BILLING_TOOLS = Object.freeze([
+  {
+    name: 'getPaymentCapabilities',
+    description: 'Discover ClipIt machine-payment capabilities, agent connection paths, safety policy, and direct x402, Stripe x402, or Stripe MPP rail readiness.',
+    costBand: 'free',
+    skill: 'billing',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'getBillingCatalog',
+    description: 'List ClipIt catalog products, prices, credit amounts, and enabled machine-payment rails.',
+    costBand: 'free',
+    skill: 'billing',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'createPaymentAttempt',
+    description: 'Create an API-key-owned machine-payment attempt and return the direct x402, Stripe x402, or Stripe MPP payment URL. This prepares a payment but does not sign a wallet transaction or supply a Stripe SPT credential.',
+    costBand: 'free',
+    skill: 'billing',
+    requiresConfirmation: true,
+    confirmation: {
+      required: true,
+      riskLevel: 'costly',
+      reason: 'Creates a payable billing attempt. Continue only after the human approved the product, amount, rail, and budget policy.',
+      actionLabel: 'create machine-payment attempt',
+      allowAutonomous: false,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        productKey: { type: 'string' },
+        providerPreference: { type: 'string', enum: ['x402_direct', 'stripe_mpp', 'stripe_x402'] },
+        idempotencyKey: { type: 'string' },
+      },
+      required: ['productKey'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'getPaymentAttempt',
+    description: 'Get the status of an API-key-owned machine-payment attempt.',
+    costBand: 'free',
+    skill: 'billing',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        attemptId: { type: 'string' },
+      },
+      required: ['attemptId'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'getPaymentReceipt',
+    description: 'Get the receipt and fulfillment records for an API-key-owned machine-payment attempt.',
+    costBand: 'free',
+    skill: 'billing',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        attemptId: { type: 'string' },
+      },
+      required: ['attemptId'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'getBillingSubscription',
+    description: 'Get the effective ClipIt billing access source for the API key owner.',
+    costBand: 'free',
+    skill: 'billing',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+]);
+
 const EXIT = {
   OK: 0,
   USAGE: 2,
@@ -61,6 +202,11 @@ const KNOWN_AGENT_TARGETS = ['codex', 'claude', 'hermes', 'generic'];
 const TRUSTED_HOSTS = new Set(['clipit.dev', 'www.clipit.dev', 'localhost', '127.0.0.1', '::1', '[::1]']);
 const AGENT_SKILL_META_FILENAME = 'SKILL.meta.json';
 
+function readPositiveIntegerEnv(name, fallback) {
+  const parsed = Number(process.env[name]);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
 function configDir() {
   if (process.env.CLIPIT_CONFIG_DIR) return process.env.CLIPIT_CONFIG_DIR;
   if (process.platform === 'win32' && process.env.APPDATA) return path.join(process.env.APPDATA, 'ClipIt');
@@ -146,6 +292,32 @@ function appendRecentEntries(config, options, entries) {
   return entries.reduce((nextConfig, entry) => appendRecentEntry(nextConfig, options, entry.type, entry.id), config);
 }
 
+function withProfileActiveContext(config, options, activeContext) {
+  const name = profileName(config, options);
+  const profiles = { ...(config.profiles || {}) };
+  profiles[name] = {
+    ...profileData(config, options),
+    activeContext,
+  };
+
+  const next = {
+    ...config,
+    profiles,
+  };
+
+  if (name === 'default') {
+    next.activeContext = activeContext;
+  }
+
+  return next;
+}
+
+async function persistActiveContext(config, options, activeContext, recent = []) {
+  let next = updateProfile(config, options, { activeContext: compactObject({ ...activeContext }) });
+  next = appendRecentEntries(next, options, recent);
+  await writeConfig(next);
+}
+
 function removeProfileFields(config, options, fields) {
   const name = profileName(config, options);
   const profiles = { ...(config.profiles || {}) };
@@ -201,21 +373,26 @@ function wantJson(options) {
 function redact(value) {
   if (typeof value !== 'string') return value;
   return value
+    .replace(/https?:\/\/(?=[^\s"'<>]*[?&](?:X-Amz-|Signature=|token=|key=))[^\s"'<>]+/gi, '[signed-url-redacted]')
+    .replace(/https?:\/\/replicate\.delivery\/[^\s"'<>]+/gi, '[generated-media-url-redacted]')
+    .replace(/https?:\/\/stream\.replicate\.com\/v1\/files\/[^\s"'<>]+/gi, '[generated-media-url-redacted]')
+    .replace(/(^|[\s"'=:(,])\/objects\/[^\s"'<>),]+/g, '$1[object-url-redacted]')
     .replace(/clipper_[a-f0-9]{24,}/gi, 'clipper_[redacted]')
     .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, 'Bearer [redacted]')
-    .replace(/([?&](?:X-Amz-Signature|Signature|token|key)=)[^&\s]+/gi, '$1[redacted]');
+    .replace(/([?&](?:X-Amz-[A-Za-z-]+|Signature|token|key)=)[^&\s]+/gi, '$1[redacted]');
 }
 
 function output(data, options) {
+  const safeData = redactDeep(data);
   if (wantJson(options)) {
-    console.log(JSON.stringify(data, null, 2));
+    console.log(JSON.stringify(safeData, null, 2));
     return;
   }
-  if (typeof data === 'string') {
-    console.log(data);
+  if (typeof safeData === 'string') {
+    console.log(safeData);
     return;
   }
-  console.log(JSON.stringify(data, null, 2));
+  console.log(JSON.stringify(safeData, null, 2));
 }
 
 function redactDeep(value) {
@@ -227,6 +404,10 @@ function redactDeep(value) {
   return value;
 }
 
+function hashText(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
 function usage() {
   return [
     'ClipIt CLI',
@@ -245,14 +426,16 @@ function usage() {
     '  clipit skills list [--json]',
     '  clipit tools list [--skill clip] [--json]',
     '  clipit tools describe <functionName>',
-    '  clipit ask "<prompt>" [--video-id id] [--clip-id id] [--conversation-id id] [--quick] [--stream] [--json]',
+    '  clipit ask "<prompt>" [--video-id id] [--clip-id id] [--conversation-id id] [--quick] [--auto-confirm-costly] [--stream] [--json]',
     '  clipit workflow status|wait <jobId> [--stream] [--json]',
     '  clipit workflow approve <jobId> --approval-id id [--decision approved|cheaper|cancelled]',
+    '  clipit mcp [stdio]',
     '  clipit run <functionName> [--params @file.json] [--clip-id id] [--video-id id] [--confirm] [--max-credits n]',
     '  clipit videos list|get|upload|import-url|transcribe|transcript|suggest-clips|delete ...',
     '  clipit clips list|get|create|update|render|download|delete ...',
     '  clipit jobs get|wait <jobId>',
     '  clipit credits balance|usage|estimate ...',
+    '  clipit billing capabilities|catalog|create-attempt|attempt|receipt|subscription ...',
     '  clipit analytics overview|top-clips|post ...',
     '  clipit exports start|list|get|wait|download|cancel ...',
     '  clipit assets list|upload|delete ...',
@@ -486,7 +669,11 @@ function maxCreditsLimit(options) {
 }
 
 function clipCostLabel(value) {
-  return `${Number(value).toFixed(2).replace(/\.00$/, '')} $CLIP`;
+  const amount = Number(value);
+  if (!Number.isFinite(amount)) return `${value} $CLIP`;
+  if (amount === 0) return '0 $CLIP';
+  const fixed = amount.toFixed(Math.abs(amount) < 0.01 ? 5 : 2).replace(/\.?0+$/, '');
+  return `${fixed} $CLIP`;
 }
 
 const SPEND_LIMIT_EXCEEDED_MESSAGE = 'Spend limit exceeded for this API key \u2014 raise the key\'s spend limit in ClipIt Settings or use a different key.';
@@ -518,6 +705,20 @@ function warnIfEstimateUnaffordable(estimates) {
   }
 }
 
+function summarizeRunEstimates(estimates) {
+  if (!Array.isArray(estimates) || !estimates.length) return null;
+  const estimatedCostClip = estimates.reduce((sum, estimate) => {
+    const value = Number(estimate?.estimatedCostClip ?? 0);
+    return sum + (Number.isFinite(value) ? value : 0);
+  }, 0);
+  return {
+    estimatedCostClip,
+    estimatedCostLabel: clipCostLabel(estimatedCostClip),
+    affordable: estimates.every((estimate) => estimate?.affordable !== false),
+    estimates,
+  };
+}
+
 function throwSpendLimitExceeded(commandKey, spendLimitViolation, estimates) {
   throw Object.assign(new Error(SPEND_LIMIT_EXCEEDED_MESSAGE), {
     exitCode: EXIT.CREDITS,
@@ -548,11 +749,52 @@ function remotionProviderCostUsd(durationSeconds, quality) {
   return Math.max(0, durationSeconds * REMOTION_ESTIMATED_USD_PER_VIDEO_SECOND * qualityMultiplier(quality));
 }
 
+function normalizeCreditEstimateRequest(request) {
+  if (
+    request.operationType === 'lambda_render'
+    && (request.provider === 'aws_lambda' || request.provider === 'remotion')
+    && request.metrics
+    && typeof request.metrics.videoSeconds === 'number'
+    && typeof request.metrics.providerCostUsd !== 'number'
+  ) {
+    return {
+      ...request,
+      metrics: {
+        ...request.metrics,
+        providerCostUsd: remotionProviderCostUsd(request.metrics.videoSeconds, 'high'),
+      },
+    };
+  }
+
+  return request;
+}
+
 function brollVideoProviderCostUsd(durationSeconds, resolution) {
   const perSecondUsd = resolution === '1080p' ? 0.28 : 0.14;
   return Math.max(0, durationSeconds * perSecondUsd);
 }
 
+function brollImageProviderCostUsd(quality) {
+  if (quality === 'low') return 0.012;
+  if (quality === 'medium') return 0.047;
+  return 0.128;
+}
+
+function ttsProviderCostUsd(text, prompt) {
+  const textBytes = Buffer.byteLength(String(text || ''), 'utf8');
+  const promptBytes = Buffer.byteLength(String(prompt || 'Say the following.'), 'utf8');
+  const estimatedInputTokens = Math.ceil((textBytes + promptBytes) / 4);
+  const estimatedOutputTokens = Math.ceil(textBytes / 3);
+  return (estimatedInputTokens / 1_000_000) * 2 + (estimatedOutputTokens / 1_000) * 0.04;
+}
+
+function videoAlterProviderCostUsd(durationSeconds, mode) {
+  const perSecond = mode === 'pro'
+    ? Number(process.env.KLING_OMNI_PRO_COST_PER_SECOND_USD ?? '0.56')
+    : Number(process.env.KLING_OMNI_STANDARD_COST_PER_SECOND_USD ?? '0.28');
+  return Math.max(0, durationSeconds * (Number.isFinite(perSecond) ? perSecond : 0.28));
+}
+
 function durationFromClip(clip, body = {}) {
   const bodyStart = Number(body.startTime);
   const bodyEnd = Number(body.endTime);
@@ -594,17 +836,57 @@ async function buildMaxCreditsEstimateRequest(config, options, spec, context = {
     return { ...spec, metrics: { generationCount: 1 } };
   }
 
+  if (spec.metrics === 'tts-provider-cost') {
+    const text = requiredString(context.body?.text, 'text');
+    return { ...spec, metrics: { providerCostUsd: ttsProviderCostUsd(text, context.body?.prompt) } };
+  }
+
   if (spec.metrics === 'broll-plan') {
     return { ...spec, metrics: { inputTokens: 4000, outputTokens: 1000 } };
   }
 
+  if (spec.metrics === 'platform-caption') {
+    return { ...spec, metrics: { inputTokens: 1500, outputTokens: 600, totalTokens: 2100 } };
+  }
+
+  if (spec.metrics === 'suggest-clips') {
+    return { ...spec, metrics: { inputTokens: 40000, outputTokens: 10000, totalTokens: 50000 } };
+  }
+
+  if (spec.metrics === 'clip-create') {
+    const audioSeconds = durationFromClip(context.body, context.body);
+    if (!Number.isFinite(audioSeconds) || audioSeconds <= 0) return null;
+    return { ...spec, metrics: { audioSeconds } };
+  }
+
+  if (spec.metrics === 'transcription-video') {
+    const videoId = requiredString(context.videoId, 'Video id');
+    const video = context.video || await apiFetch(config, options, 'GET', `/api/v1/videos/${encodeURIComponent(videoId)}`);
+    const audioSeconds = Number(video?.durationSeconds ?? video?.duration);
+    if (!Number.isFinite(audioSeconds) || audioSeconds <= 0) return null;
+    return { ...spec, metrics: { audioSeconds } };
+  }
+
+  if (spec.metrics === 'video-upload-storage') {
+    const bytes = Number(context.bytes);
+    if (!Number.isFinite(bytes) || bytes <= 0) return null;
+    return { ...spec, metrics: { generationCount: bytes / BYTES_PER_GB } };
+  }
+
   if (spec.metrics === 'broll-images') {
     const mode = context.body?.mode || 'single_image';
-    return { ...spec, metrics: { generationCount: mode === 'start_end_frame' ? 3 : 1 } };
+    const generationCount = mode === 'start_end_frame' ? 3 : 1;
+    return {
+      ...spec,
+      metrics: {
+        generationCount,
+        providerCostUsd: brollImageProviderCostUsd(context.body?.imageQuality) * generationCount,
+      },
+    };
   }
 
   if (spec.metrics === 'broll-video') {
-    const durationSeconds = Number(context.body?.durationSeconds ?? 6);
+    const durationSeconds = Number(context.body?.durationSeconds ?? context.body?.duration ?? 6);
     const resolution = context.body?.resolution || '720p';
     if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return null;
     return {
@@ -616,6 +898,21 @@ async function buildMaxCreditsEstimateRequest(config, options, spec, context = {
     };
   }
 
+  if (spec.metrics === 'video-alter-provider-cost') {
+    const durationSeconds = Number(
+      context.body?.duration
+        ?? (Number(context.body?.sourceEnd) - Number(context.body?.sourceStart)),
+    );
+    if (!Number.isFinite(durationSeconds) || durationSeconds < 3 || durationSeconds > 10) return null;
+    return {
+      ...spec,
+      metrics: {
+        videoSeconds: durationSeconds,
+        providerCostUsd: videoAlterProviderCostUsd(durationSeconds, context.body?.mode),
+      },
+    };
+  }
+
   if (spec.metrics === 'social-platforms') {
     const platforms = Array.isArray(context.body?.platforms) ? context.body.platforms : [];
     if (!platforms.length) return null;
@@ -640,8 +937,70 @@ async function buildMaxCreditsEstimateRequest(config, options, spec, context = {
   return null;
 }
 
+async function buildStaticRunEstimates(config, options, functionName, parameters, payload) {
+  const specs = RUN_MAX_CREDITS_ESTIMATE_MAP[functionName];
+  if (!specs) return null;
+
+  const body = parameters && typeof parameters === 'object' && !Array.isArray(parameters) ? parameters : {};
+  const requests = [];
+  for (const spec of specs) {
+    const request = await buildMaxCreditsEstimateRequest(config, options, spec, {
+      body,
+      clipId: payload?.clipId || body.clipId,
+      videoId: payload?.videoId || body.videoId,
+    });
+    if (!request) return null;
+    requests.push(compactObject({
+      operationType: request.operationType,
+      provider: request.provider,
+      modelId: request.modelId,
+      metrics: request.metrics,
+    }));
+  }
+
+  const estimates = [];
+  for (const request of requests) {
+    const estimate = await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', request);
+    estimates.push({
+      operationType: request.operationType,
+      provider: request.provider,
+      modelId: request.modelId,
+      estimatedCostClip: Number(estimate?.estimatedCostClip ?? 0),
+      affordable: estimate?.affordable,
+      spendLimitViolation: estimate?.spendLimitViolation ?? null,
+    });
+  }
+
+  return estimates;
+}
+
+function currentInvocationWantsJson() {
+  return process.argv.some((arg) => arg === '--json' || arg === '--json=true');
+}
+
 function printEstimateUnavailable(commandKey) {
-  console.error(`estimate unavailable for ${commandKey}; --confirm is required.`);
+  if (!currentInvocationWantsJson()) {
+    console.error(`estimate unavailable for ${commandKey}; --confirm is required.`);
+  }
+}
+
+function throwMaxCreditsEstimateUnavailable(commandKey) {
+  if (!currentInvocationWantsJson()) {
+    console.error(`estimate unavailable for ${commandKey}; --max-credits cannot be enforced.`);
+  }
+  throw Object.assign(
+    new Error(`Cannot enforce --max-credits for ${commandKey} because no cost estimate is available.`),
+    { exitCode: EXIT.CONFIRMATION },
+  );
+}
+
+function estimatedClipCostFromData(data) {
+  if (!data || typeof data !== 'object') return null;
+  for (const key of ['estimatedCostClip', 'totalEstimatedCostClip', 'costClip', 'totalCostClip']) {
+    const value = Number(data[key]);
+    if (Number.isFinite(value)) return value;
+  }
+  return null;
 }
 
 async function enforceMaxCredits(config, options, commandKey, context = {}) {
@@ -705,20 +1064,119 @@ async function enforceMaxCredits(config, options, commandKey, context = {}) {
   }
 }
 
-async function enforceRunMaxCredits(config, options, functionName) {
-  if (maxCreditsLimit(options) === null) return;
+async function enforceRunMaxCredits(config, options, functionName, parameters = {}, payload = {}) {
+  const limit = maxCreditsLimit(options);
+  const needsConfirmationPreflight = !boolOption(options.confirm);
+  if (limit === null && !needsConfirmationPreflight) return null;
+
   const catalog = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
   const tools = Array.isArray(catalog?.tools) ? catalog.tools : Array.isArray(catalog) ? catalog : [];
   const tool = tools.find((item) => item.name === functionName);
   const runEstimate = tool?.estimate ?? tool?.confirmation?.estimate ?? tool?.confirmation?.costEstimate ?? null;
+  const isMetered = Boolean(tool?.costBand && tool.costBand !== 'free');
+  const isMeteredExempt = RUN_METERED_CONFIRMATION_EXEMPTIONS.has(functionName);
+
+  let staticEstimates = null;
+  if (!runEstimate && (limit !== null || needsConfirmationPreflight)) {
+    staticEstimates = await buildStaticRunEstimates(config, options, functionName, parameters, payload);
+  }
+
+  if (limit === null) {
+    const estimates = staticEstimates || (runEstimate ? [runEstimate] : null);
+    const estimateSummary = summarizeRunEstimates(estimates);
+    if (estimateSummary && (tool?.confirmation?.required || (isMetered && !isMeteredExempt))) {
+      warnIfEstimateUnaffordable(estimates);
+      throw Object.assign(
+        new Error(`Estimated cost ${estimateSummary.estimatedCostLabel} for run ${functionName}; --confirm is required.`),
+        {
+          exitCode: EXIT.CONFIRMATION,
+          data: {
+            command: `run ${functionName}`,
+            estimate: estimateSummary,
+          },
+        },
+      );
+    }
+    if (tool?.confirmation?.required) {
+      if (isMetered) printEstimateUnavailable(`run ${functionName}`);
+      requireConfirm(options, `Running confirmation-gated tool ${functionName}`);
+      return;
+    }
+    if (isMetered && !isMeteredExempt) {
+      printEstimateUnavailable(`run ${functionName}`);
+      requireConfirm(options, `Running metered tool ${functionName}`);
+      return;
+    }
+    return null;
+  }
+
+  if (staticEstimates) {
+    const spendLimitViolation = staticEstimates.find((estimate) => estimate.spendLimitViolation)?.spendLimitViolation;
+    if (spendLimitViolation) throwSpendLimitExceeded(`run ${functionName}`, spendLimitViolation, staticEstimates);
+    warnIfEstimateUnaffordable(staticEstimates);
+
+    const estimatedCostClip = staticEstimates.reduce((sum, estimate) => sum + estimate.estimatedCostClip, 0);
+    if (estimatedCostClip > limit) {
+      throw Object.assign(
+        new Error(`Estimated cost ${clipCostLabel(estimatedCostClip)} exceeds --max-credits ${clipCostLabel(limit)} for run ${functionName}.`),
+        {
+          exitCode: EXIT.CONFIRMATION,
+          data: {
+            command: `run ${functionName}`,
+            maxCredits: limit,
+            estimatedCostClip,
+            estimates: staticEstimates,
+          },
+        },
+      );
+    }
+    if (tool?.confirmation?.required || (isMetered && !isMeteredExempt)) {
+      requireConfirm(
+        options,
+        tool?.confirmation?.required ? `Running confirmation-gated tool ${functionName}` : `Running metered tool ${functionName}`,
+      );
+    }
+    return summarizeRunEstimates(staticEstimates);
+  }
+
   const spendLimitViolation = spendLimitViolationFromData(runEstimate) ?? spendLimitViolationFromData(tool?.confirmation);
   if (spendLimitViolation) throwSpendLimitExceeded(`run ${functionName}`, spendLimitViolation, runEstimate ? [runEstimate] : []);
   if (runEstimate?.affordable === false || tool?.confirmation?.affordable === false) {
     console.error('Warning: estimated cost exceeds your current balance.');
   }
-  if (!tool?.confirmation?.required) return;
-  printEstimateUnavailable(`run ${functionName}`);
-  requireConfirm(options, `Running confirmation-gated tool ${functionName}`);
+  if (!runEstimate && isMetered && !isMeteredExempt) {
+    throwMaxCreditsEstimateUnavailable(`run ${functionName}`);
+  }
+  if (!runEstimate && tool?.confirmation?.required) {
+    throwMaxCreditsEstimateUnavailable(`run ${functionName}`);
+  }
+  if (runEstimate) {
+    const estimatedCostClip = estimatedClipCostFromData(runEstimate);
+    if (estimatedCostClip === null) {
+      throwMaxCreditsEstimateUnavailable(`run ${functionName}`);
+    }
+    if (estimatedCostClip > limit) {
+      throw Object.assign(
+        new Error(`Estimated cost ${clipCostLabel(estimatedCostClip)} exceeds --max-credits ${clipCostLabel(limit)} for run ${functionName}.`),
+        {
+          exitCode: EXIT.CONFIRMATION,
+          data: {
+            command: `run ${functionName}`,
+            maxCredits: limit,
+            estimatedCostClip,
+            estimates: [runEstimate],
+          },
+        },
+      );
+    }
+  }
+  if (tool?.confirmation?.required || (isMetered && !isMeteredExempt)) {
+    requireConfirm(
+      options,
+      tool?.confirmation?.required ? `Running confirmation-gated tool ${functionName}` : `Running metered tool ${functionName}`,
+    );
+  }
+  return runEstimate ? summarizeRunEstimates([runEstimate]) : null;
 }
 
 async function login(config, options) {
@@ -967,7 +1425,7 @@ async function contextCommand(config, options, action) {
   }
 
   if (action === 'use') {
-    const activeContext = await buildContext({ ...config, activeContext: {} }, options);
+    const activeContext = await buildContext(withProfileActiveContext(config, options, {}), options);
     let next = updateProfile(config, options, { activeContext });
     next = appendRecentEntries(next, options, [
       { type: 'video', id: activeContext.videoId },
@@ -988,6 +1446,51 @@ async function contextCommand(config, options, action) {
   throw Object.assign(new Error(`Unknown context command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
+function applyContextToAgentPayload(payload, parameters, context) {
+  const canMutateParameters = parameters && typeof parameters === 'object' && !Array.isArray(parameters);
+  const hadExplicitVideoId = canMutateParameters && parameters.videoId !== undefined;
+  for (const field of ['videoId', 'clipId', 'projectId', 'sequenceId']) {
+    if (context[field] && !payload[field]) {
+      payload[field] = context[field];
+      if (canMutateParameters && parameters[field] === undefined) {
+        parameters[field] = context[field];
+      }
+    }
+  }
+  if (canMutateParameters
+    && CLIP_IDS_CONTEXT_TOOLS.has(payload.functionName)
+    && parameters.clipIds === undefined
+    && !hadExplicitVideoId) {
+    const selectedClipIds = Array.isArray(context.selectedClipIds)
+      ? context.selectedClipIds.filter(Boolean).map(String)
+      : [];
+    const clipId = parameters.clipId || (selectedClipIds.length ? null : context.clipId);
+    if (clipId) parameters.clipIds = [String(clipId)];
+    else if (selectedClipIds.length) parameters.clipIds = selectedClipIds;
+  }
+  if (context.selectedClipIds) payload.selectedClipIds = context.selectedClipIds;
+  if (context.playheadPosition !== undefined) payload.playheadPosition = context.playheadPosition;
+  if (Object.keys(context).length) payload.context = context.context || context;
+}
+
+function normalizeAgentExecuteResult(result) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result;
+  const nested = result.result;
+  if (!nested || typeof nested !== 'object' || Array.isArray(nested) || nested.requiresConfirmation !== true) {
+    return result;
+  }
+
+  return compactObject({
+    ...result,
+    requiresConfirmation: true,
+    confirmationTool: result.confirmationTool ?? nested.confirmationTool ?? nested.functionName,
+    confirmationParams: result.confirmationParams ?? nested.confirmationParams ?? nested.parameters,
+    confirmation: result.confirmation ?? nested.confirmation,
+    estimate: result.estimate ?? nested.estimate,
+    preview: result.preview ?? nested.preview,
+  });
+}
+
 async function runTool(config, options, functionName) {
   if (!functionName) throw Object.assign(new Error('Function name is required.'), { exitCode: EXIT.USAGE });
   const parameters = await readJsonOption(options.params || options['params-json']);
@@ -1003,23 +1506,29 @@ async function runTool(config, options, functionName) {
     ['project-id', 'projectId'],
     ['sequence-id', 'sequenceId'],
   ]) {
-    if (options[flag]) payload[field] = String(options[flag]);
+    if (options[flag]) {
+      const value = String(options[flag]);
+      payload[field] = value;
+      if (parameters && typeof parameters === 'object' && !Array.isArray(parameters) && parameters[field] === undefined) {
+        parameters[field] = value;
+      }
+    }
   }
-  if (context.videoId && !payload.videoId) payload.videoId = context.videoId;
-  if (context.clipId && !payload.clipId) payload.clipId = context.clipId;
-  if (context.projectId && !payload.projectId) payload.projectId = context.projectId;
-  if (context.sequenceId && !payload.sequenceId) payload.sequenceId = context.sequenceId;
-  if (context.selectedClipIds) payload.selectedClipIds = context.selectedClipIds;
-  if (context.playheadPosition !== undefined) payload.playheadPosition = context.playheadPosition;
-  if (Object.keys(context).length) payload.context = context.context || context;
-  await enforceRunMaxCredits(config, options, functionName);
-  const result = await apiFetch(config, options, 'POST', '/api/v1/agent/execute', payload);
-  if (result?.requiresConfirmation && !payload.confirmed) {
-    output(result, options);
+  applyContextToAgentPayload(payload, parameters, context);
+  if (RUN_CONFIRMATION_LABELS[functionName]) {
+    confirmPaid(options, RUN_CONFIRMATION_LABELS[functionName]);
+  }
+  const estimate = await enforceRunMaxCredits(config, options, functionName, parameters, payload);
+  const result = normalizeAgentExecuteResult(await apiFetch(config, options, 'POST', '/api/v1/agent/execute', payload));
+  const outputResult = estimate && result && typeof result === 'object' && !Array.isArray(result) && result.estimate === undefined
+    ? { ...result, estimate }
+    : result;
+  if (result?.requiresConfirmation && !payload.confirmed && !RUN_METERED_CONFIRMATION_EXEMPTIONS.has(functionName)) {
+    output(outputResult, options);
     process.exitCode = EXIT.CONFIRMATION;
     return;
   }
-  output(result, options);
+  output(outputResult, options);
 }
 
 function workflowEndpoint(jobId) {
@@ -1152,6 +1661,7 @@ async function askWorkflow(config, options, promptParts) {
   }
   if (options['conversation-id']) payload.conversationId = String(options['conversation-id']);
   if (options.quick !== undefined) payload.quickMode = boolOption(options.quick);
+  if (options['auto-confirm-costly'] !== undefined) payload.autoConfirmCostlyTools = boolOption(options['auto-confirm-costly']);
 
   const accepted = await apiFetch(config, options, 'POST', '/api/v1/agent/orchestrate', payload);
   if (boolOption(options['no-wait'])) {
@@ -1199,12 +1709,13 @@ async function workflow(config, options, action, args) {
     }
 
     const redactedAccepted = redactDeep(accepted);
-    if (wantJson(options)) {
+    if (boolOption(options['no-wait'])) {
       output(redactedAccepted, options);
-    } else {
+      return;
+    }
+    if (!wantJson(options)) {
       console.log(`Continuation workflow queued: ${redactedAccepted.jobId}`);
     }
-    if (boolOption(options['no-wait'])) return;
     await pollWorkflow(config, options, accepted.jobId);
     return;
   }
@@ -1240,6 +1751,24 @@ function formatMb(bytes) {
   return (bytes / (1024 * 1024)).toFixed(1);
 }
 
+function assertDirectVideoUploadSize(filePath, sizeBytes) {
+  if (sizeBytes <= DIRECT_VIDEO_UPLOAD_MAX_BYTES) return;
+  throw Object.assign(
+    new Error(
+      `Video file is ${formatMb(sizeBytes)} MB, above the direct CLI upload limit of ${formatMb(DIRECT_VIDEO_UPLOAD_MAX_BYTES)} MB. ` +
+      'Use `clipit videos import-url` for URL sources or a server-side/resumable upload path; direct CLI upload is likely to fail with 413 before ClipIt can process it.',
+    ),
+    {
+      exitCode: EXIT.USAGE,
+      data: {
+        filePath,
+        sizeBytes,
+        maxBytes: DIRECT_VIDEO_UPLOAD_MAX_BYTES,
+      },
+    },
+  );
+}
+
 function createUploadProgress(options, totalBytes) {
   if (!shouldReportUploadProgress(options) || !Number.isFinite(totalBytes) || totalBytes <= 0) {
     return { track() {}, finish() {} };
@@ -1286,6 +1815,7 @@ async function uploadVideo(config, options, filePath) {
   if (!stat.isFile()) {
     throw Object.assign(new Error(`Upload path is not a file: ${resolved}`), { exitCode: EXIT.USAGE });
   }
+  assertDirectVideoUploadSize(resolved, stat.size);
   const filename = options.filename || path.basename(resolved);
   const contentType = mimeForPath(resolved);
   const boundary = `clipit-cli-${randomBytes(12).toString('hex')}`;
@@ -1295,14 +1825,25 @@ async function uploadVideo(config, options, filePath) {
   const footerLength = Buffer.byteLength(`\r\n--${boundary}--\r\n`);
   const progress = createUploadProgress(options, stat.size);
   const body = multipartFileBody(resolved, filename, contentType, boundary, progress);
+  await enforceMaxCredits(config, options, 'videos upload', { bytes: stat.size });
+  confirmPaid(options, 'Uploading a video');
   try {
-    output(await apiFetch(config, options, 'POST', '/api/v1/videos', body, {
+    const result = await apiFetch(config, options, 'POST', '/api/v1/videos', body, {
       rawBody: true,
       headers: {
         'Content-Type': `multipart/form-data; boundary=${boundary}`,
         'Content-Length': String(headerLength + stat.size + footerLength),
       },
-    }), options);
+    });
+    if (result?.videoId) {
+      await persistActiveContext(
+        config,
+        options,
+        { videoId: result.videoId },
+        [{ type: 'video', id: result.videoId }],
+      );
+    }
+    output(result, options);
   } finally {
     progress.finish();
   }
@@ -1324,6 +1865,7 @@ async function videos(config, options, action, args) {
     const url = args[0] || options.url;
     if (!url) throw Object.assign(new Error('URL is required.'), { exitCode: EXIT.USAGE });
     await enforceMaxCredits(config, options, 'videos import-url', { url });
+    confirmPaid(options, 'Importing a video from URL');
     output(await apiFetch(config, options, 'POST', '/api/v1/videos/from-url', { url, title: options.title }), options);
     return;
   }
@@ -1333,6 +1875,8 @@ async function videos(config, options, action, args) {
   }
   if (action === 'transcribe') {
     if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
+    await enforceMaxCredits(config, options, 'videos transcribe', { videoId: args[0] });
+    confirmPaid(options, 'Transcribing a video');
     output(await apiFetch(config, options, 'POST', `/api/v1/videos/${encodeURIComponent(args[0])}/transcribe`, {}), options);
     return;
   }
@@ -1352,6 +1896,8 @@ async function videos(config, options, action, args) {
           targetPlatforms: stringList(options.platforms),
           themes: stringList(options.themes),
         };
+    await enforceMaxCredits(config, options, 'videos suggest-clips', { videoId: args[0], body });
+    confirmPaid(options, 'Suggesting clips');
     output(await apiFetch(config, options, 'POST', `/api/v1/videos/${encodeURIComponent(args[0])}/suggest-clips`, body), options);
     return;
   }
@@ -1394,7 +1940,21 @@ async function clips(config, options, action, args) {
     if (!body.videoId) throw Object.assign(new Error('--video-id is required.'), { exitCode: EXIT.USAGE });
     if (body.startTime === undefined) throw Object.assign(new Error('--start is required.'), { exitCode: EXIT.USAGE });
     if (body.endTime === undefined) throw Object.assign(new Error('--end is required.'), { exitCode: EXIT.USAGE });
-    output(await apiFetch(config, options, 'POST', '/api/v1/clips', body), options);
+    await enforceMaxCredits(config, options, 'clips create', { body });
+    confirmPaid(options, 'Creating a clip');
+    const result = await apiFetch(config, options, 'POST', '/api/v1/clips', body);
+    if (result?.id) {
+      await persistActiveContext(
+        config,
+        options,
+        { videoId: result.videoId || body.videoId, clipId: result.id },
+        [
+          { type: 'video', id: result.videoId || body.videoId },
+          { type: 'clip', id: result.id },
+        ],
+      );
+    }
+    output(result, options);
     return;
   }
   if (action === 'update') {
@@ -1428,6 +1988,7 @@ async function clips(config, options, action, args) {
       if (body[key] === undefined) delete body[key];
     }
     await enforceMaxCredits(config, options, 'clips render', { clipId: args[0], body });
+    confirmPaid(options, 'Rendering a clip');
     output(await apiFetch(config, options, 'POST', `/api/v1/clips/${encodeURIComponent(args[0])}/render`, body), options);
     return;
   }
@@ -1460,18 +2021,78 @@ async function credits(config, options, action) {
   if (action === 'estimate') {
     const operationType = requiredString(options['operation-type'], '--operation-type');
     const provider = requiredString(options.provider, '--provider');
-    const metrics = await readMetricsOption(options.metrics);
-    output(await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', compactObject({
+    const metrics = await readMetricsOption(options.metrics ?? options.metadata);
+    const request = normalizeCreditEstimateRequest(compactObject({
       operationType,
       provider,
       modelId: options['model-id'],
       metrics,
-    })), options);
+    }));
+    output(await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', request), options);
     return;
   }
   throw Object.assign(new Error(`Unknown credits command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
+function normalizeBillingProvider(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const provider = String(value);
+  if (!BILLING_PROVIDER_PREFERENCES.has(provider)) {
+    throw Object.assign(
+      new Error(`--provider must be one of: ${Array.from(BILLING_PROVIDER_PREFERENCES).join(', ')}.`),
+      { exitCode: EXIT.USAGE },
+    );
+  }
+  return provider;
+}
+
+function buildBillingAttemptBody(input = {}) {
+  return compactObject({
+    productKey: requiredString(input.productKey ?? input['product-key'] ?? input.product ?? input.key, '--product-key'),
+    providerPreference: normalizeBillingProvider(input.providerPreference ?? input.provider ?? input.rail),
+    idempotencyKey: input.idempotencyKey ?? input['idempotency-key'],
+  });
+}
+
+function billingAttemptId(args, options) {
+  return requiredString(args[0] ?? options['attempt-id'] ?? options.attemptId, 'Attempt id');
+}
+
+async function billing(config, options, action, args = []) {
+  if (action === 'capabilities') {
+    output(await apiFetch(config, options, 'GET', '/api/v1/agent/payment-capabilities', undefined, { noAuth: true }), options);
+    return;
+  }
+  if (action === 'catalog') {
+    output(await apiFetch(config, options, 'GET', '/api/v1/billing/catalog', undefined, { noAuth: true }), options);
+    return;
+  }
+  if (action === 'create-attempt') {
+    requireConfirm(options, 'Creating a machine-payment attempt');
+    const body = buildBillingAttemptBody({
+      ...options,
+      productKey: options['product-key'] ?? options.productKey ?? args[0],
+    });
+    output(await apiFetch(config, options, 'POST', '/api/v1/billing/agent-payments', body), options);
+    return;
+  }
+  if (action === 'attempt') {
+    const attemptId = billingAttemptId(args, options);
+    output(await apiFetch(config, options, 'GET', `/api/v1/billing/agent-payments/${encodeURIComponent(attemptId)}`), options);
+    return;
+  }
+  if (action === 'receipt') {
+    const attemptId = billingAttemptId(args, options);
+    output(await apiFetch(config, options, 'GET', `/api/v1/billing/agent-payments/${encodeURIComponent(attemptId)}/receipt`), options);
+    return;
+  }
+  if (action === 'subscription') {
+    output(await apiFetch(config, options, 'GET', '/api/v1/billing/subscription'), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown billing command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
 async function analytics(config, options, action, args) {
   if (action === 'overview') {
     const suffix = queryString({ days: options.days ?? 30 });
@@ -1551,7 +2172,7 @@ async function exportsCommand(config, options, action, args) {
     return;
   }
   if (action === 'list') {
-    output(await apiFetch(config, options, 'GET', `/api/v1/exports${queryString({ limit: options.limit, offset: options.offset })}`), options);
+    output(await apiFetch(config, options, 'GET', `/api/v1/exports${queryString({ limit: options.limit, offset: options.offset, clipId: options['clip-id'] })}`), options);
     return;
   }
   if (action === 'get') {
@@ -1572,6 +2193,7 @@ async function exportsCommand(config, options, action, args) {
   }
   if (action === 'cancel') {
     const jobId = requiredString(args[0], 'Export job id');
+    requireConfirm(options, 'Cancelling an export');
     output(await apiFetch(config, options, 'POST', `/api/v1/exports/${encodeURIComponent(jobId)}/cancel`, {}), options);
     return;
   }
@@ -1621,6 +2243,7 @@ async function uploadAsset(config, options, filePath) {
     size: stat.size,
     kind: options.kind,
   });
+  requireConfirm(options, 'Uploading an asset');
   const signed = await apiFetch(config, options, 'POST', '/api/v1/assets/sign-upload', signBody);
   if (!signed?.uploadUrl || !signed?.key || !signed?.assetId) {
     throw Object.assign(new Error('Asset sign-upload returned an unexpected response.'), { exitCode: EXIT.SERVER, data: signed });
@@ -1809,19 +2432,28 @@ async function jobs(config, options, action, args) {
   const jobId = args[0];
   if (!jobId) throw Object.assign(new Error('Job id is required.'), { exitCode: EXIT.USAGE });
   const startedAt = Date.now();
-  const timeoutMs = numberOption(options['timeout-ms'], '--timeout-ms');
-  const intervalMs = numberOption(options.interval, '--interval') || 3000;
+  const requestedTimeoutMs = numberOption(options['timeout-ms'], '--timeout-ms');
+  const requestedIntervalMs = numberOption(options.interval, '--interval');
   while (true) {
     const job = await apiFetch(config, options, 'GET', `/api/v1/jobs/${encodeURIComponent(jobId)}`);
     if (action === 'get' || TERMINAL_JOB_STATUSES.has(job.status)) {
       output(job, options);
       return;
     }
-    if (options.stream) console.log(JSON.stringify({ type: 'job.progress', job }));
+    if (options.stream) console.log(JSON.stringify({ type: 'job.progress', job: redactDeep(job) }));
+    const serverMinimumWaitMs = typeof job.minimumWaitSeconds === 'number'
+      ? Math.max(0, job.minimumWaitSeconds * 1000)
+      : 0;
+    const timeoutMs = requestedTimeoutMs
+      ? Math.max(requestedTimeoutMs, serverMinimumWaitMs)
+      : undefined;
     if (timeoutMs && Date.now() - startedAt > timeoutMs) {
       throw Object.assign(new Error(`Timed out waiting for job ${jobId}.`), { exitCode: EXIT.SERVER });
     }
-    await sleep(intervalMs);
+    const serverIntervalMs = typeof job.recommendedPollIntervalSeconds === 'number'
+      ? Math.max(1000, job.recommendedPollIntervalSeconds * 1000)
+      : 0;
+    await sleep(requestedIntervalMs || serverIntervalMs || 3000);
   }
 }
 
@@ -1865,9 +2497,8 @@ async function appUrl(config, options, kind, id) {
     params.set('clip', id);
     return `${baseUrl}/clips/review?${params.toString()}`;
   }
-  // A video link should open that video's clips in the Review page (which keys
-  // off ?video=), not the generic /clips library list which has no selection.
-  if (kind === 'video') return `${baseUrl}/clips/review${id ? `?video=${encodeURIComponent(id)}` : ''}`;
+  // A video-level agent result should land in the Agent Content library tab.
+  if (kind === 'video') return `${baseUrl}/clips${id ? `?tab=agent&video=${encodeURIComponent(id)}` : '?tab=agent'}`;
   // The editor lives at /editor and reads ?project= (NOT /editor/projects, which
   // redirects to /clips and drops the query — the same dead-end class as the
   // clip/video link bug). There is no surface that consumes a raw sequenceId, so
@@ -1904,24 +2535,498 @@ async function links(config, options, kind, id) {
   output(result, options);
 }
 
+function mcpToolInputSchema(tool) {
+  const schema = tool?.inputSchema || tool?.parametersSchema || tool?.parameterSchema || tool?.parameters;
+  if (schema && typeof schema === 'object' && !Array.isArray(schema)) return schema;
+  return { type: 'object', additionalProperties: true };
+}
+
+function mcpToolConfirmationDescription(tool) {
+  if (!mcpToolRequiresConfirmation(tool, tool?.name)) return null;
+  const parts = [
+    tool?.confirmation?.riskLevel ? `risk=${tool.confirmation.riskLevel}` : null,
+    tool?.confirmation?.reason || null,
+  ].filter(Boolean);
+  if (parts.length) return parts.join('; ');
+
+  const costBand = String(tool?.costBand || tool?.cost_band || '').toLowerCase();
+  if (costBand && costBand !== 'free' && costBand !== 'none') {
+    return `cost=${costBand}; may spend credits or mutate user-visible ClipIt state. Ask the user before retrying with confirmed:true.`;
+  }
+  return 'may mutate user-visible ClipIt state. Ask the user before retrying with confirmed:true.';
+}
+
+function mcpToolDescription(tool) {
+  const confirmationDescription = mcpToolConfirmationDescription(tool);
+  return [
+    tool?.description,
+    tool?.skill ? `Skill: ${tool.skill}` : null,
+    tool?.costBand ? `Cost: ${tool.costBand}` : null,
+    confirmationDescription ? `Confirmation required: ${confirmationDescription}` : null,
+  ].filter(Boolean).join('\n');
+}
+
+function mcpToolRequiresConfirmation(tool, name) {
+  if (RUN_METERED_CONFIRMATION_EXEMPTIONS.has(name)) return false;
+  if (RUN_CONFIRMATION_LABELS[name]) return true;
+  if (tool?.confirmation?.required) return true;
+  if (tool?.requiresConfirmation === true) return true;
+  const costBand = String(tool?.costBand || tool?.cost_band || '').toLowerCase();
+  return Boolean(costBand && costBand !== 'free' && costBand !== 'none');
+}
+
+function readMcpMaxCredits(parameters) {
+  if (!parameters || typeof parameters !== 'object' || Array.isArray(parameters)) return null;
+  let raw;
+  for (const key of ['maxCredits', 'max_credits', 'maxCreditsClip']) {
+    if (raw === undefined && parameters[key] !== undefined) raw = parameters[key];
+    delete parameters[key];
+  }
+  if (raw === undefined) return null;
+  const limit = Number(raw);
+  if (!Number.isFinite(limit) || limit < 0) {
+    throw new Error('MCP tools/call maxCredits must be 0 or greater.');
+  }
+  return limit;
+}
+
+async function mcpEstimatePayload(config, options, tool, name, parameters, payload) {
+  const runEstimate = tool?.estimate ?? tool?.confirmation?.estimate ?? tool?.confirmation?.costEstimate ?? null;
+  if (runEstimate) {
+    const estimatedCostClip = estimatedClipCostFromData(runEstimate);
+    return compactObject({
+      estimate: compactObject({
+        estimatedCostClip,
+        estimatedCostLabel: estimatedCostClip === null ? undefined : clipCostLabel(estimatedCostClip),
+        affordable: runEstimate.affordable,
+        estimates: [runEstimate],
+      }),
+    });
+  }
+
+  try {
+    const estimates = await buildStaticRunEstimates(config, options, name, parameters, payload);
+    if (estimates?.length) {
+      const estimatedCostClip = estimates.reduce((sum, estimate) => sum + Number(estimate.estimatedCostClip ?? 0), 0);
+      return {
+        estimate: {
+          estimatedCostClip,
+          estimatedCostLabel: clipCostLabel(estimatedCostClip),
+          affordable: estimates.every((estimate) => estimate.affordable !== false),
+          estimates,
+        },
+      };
+    }
+  } catch (error) {
+    return { estimateUnavailable: redact(error.message || String(error)) };
+  }
+
+  const costBand = String(tool?.costBand || tool?.cost_band || '').toLowerCase();
+  if (costBand && costBand !== 'free' && costBand !== 'none') {
+    return { estimateUnavailable: 'No local cost estimate is available for this tool; use estimateOperationCost before approval when possible.' };
+  }
+  return {};
+}
+
+async function mcpMaxCreditsResult(config, options, tool, name, parameters, payload, maxCredits) {
+  if (maxCredits === null) return null;
+  const estimatePayload = await mcpEstimatePayload(config, options, tool, name, parameters, payload);
+  if (!estimatePayload.estimate) {
+    const costBand = String(tool?.costBand || tool?.cost_band || '').toLowerCase();
+    if (!mcpToolRequiresConfirmation(tool, name) && (!costBand || costBand === 'free' || costBand === 'none')) {
+      return null;
+    }
+    return {
+      error: 'max_credits_unenforceable',
+      functionName: name,
+      maxCredits,
+      maxCreditsLabel: clipCostLabel(maxCredits),
+      estimateUnavailable: estimatePayload.estimateUnavailable || 'No local cost estimate is available for this tool.',
+    };
+  }
+  const estimatedCostClip = Number(estimatePayload.estimate.estimatedCostClip);
+  if (!Number.isFinite(estimatedCostClip)) {
+    return {
+      error: 'max_credits_unenforceable',
+      functionName: name,
+      maxCredits,
+      maxCreditsLabel: clipCostLabel(maxCredits),
+      estimate: estimatePayload.estimate,
+      estimateUnavailable: 'The available estimate did not include an estimatedCostClip value.',
+    };
+  }
+  if (estimatedCostClip > maxCredits) {
+    return {
+      error: 'max_credits_exceeded',
+      functionName: name,
+      maxCredits,
+      maxCreditsLabel: clipCostLabel(maxCredits),
+      estimatedCostClip,
+      estimatedCostLabel: clipCostLabel(estimatedCostClip),
+      estimate: estimatePayload.estimate,
+    };
+  }
+  return null;
+}
+
+async function mcpConfirmationPayload(config, options, tool, name, parameters, payload, maxCredits = null) {
+  const reason = tool?.confirmation?.reason || `${name} may spend credits or mutate user-visible ClipIt state. Ask the user before retrying with confirmed:true.`;
+  const confirmation = compactObject({
+    requiresConfirmation: true,
+    functionName: name,
+    reason,
+    confirmation: tool?.confirmation || undefined,
+    confirmationParams: parameters,
+    retryArguments: {
+      ...(parameters || {}),
+      confirmed: true,
+      maxCredits: maxCredits ?? undefined,
+    },
+  });
+
+  Object.assign(confirmation, await mcpEstimatePayload(config, options, tool, name, parameters, payload));
+
+  return confirmation;
+}
+
+function mcpTextResult(value, isError = false) {
+  const text = typeof value === 'string' ? value : JSON.stringify(redactDeep(value), null, 2);
+  return compactObject({
+    content: [{ type: 'text', text }],
+    isError: isError || undefined,
+  });
+}
+
+async function fetchMcpTools(config, options) {
+  const response = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
+  return mergeMcpTools(Array.isArray(response?.tools) ? response.tools : []);
+}
+
+function mergeMcpTools(serverTools) {
+  const seen = new Set();
+  const merged = [];
+  for (const tool of [...LOCAL_MCP_BILLING_TOOLS, ...serverTools]) {
+    if (typeof tool?.name !== 'string' || seen.has(tool.name)) continue;
+    seen.add(tool.name);
+    merged.push(tool);
+  }
+  return merged;
+}
+
+function localMcpBillingTool(name) {
+  return LOCAL_MCP_BILLING_TOOLS.find((tool) => tool.name === name) || null;
+}
+
+async function handleLocalMcpBillingTool(config, options, name, parameters = {}) {
+  if (name === 'getPaymentCapabilities') {
+    return apiFetch(config, options, 'GET', '/api/v1/agent/payment-capabilities', undefined, { noAuth: true });
+  }
+  if (name === 'getBillingCatalog') {
+    return apiFetch(config, options, 'GET', '/api/v1/billing/catalog', undefined, { noAuth: true });
+  }
+  if (name === 'createPaymentAttempt') {
+    return apiFetch(config, options, 'POST', '/api/v1/billing/agent-payments', buildBillingAttemptBody(parameters));
+  }
+  if (name === 'getPaymentAttempt') {
+    const attemptId = requiredString(parameters.attemptId ?? parameters.attempt_id, 'attemptId');
+    return apiFetch(config, options, 'GET', `/api/v1/billing/agent-payments/${encodeURIComponent(attemptId)}`);
+  }
+  if (name === 'getPaymentReceipt') {
+    const attemptId = requiredString(parameters.attemptId ?? parameters.attempt_id, 'attemptId');
+    return apiFetch(config, options, 'GET', `/api/v1/billing/agent-payments/${encodeURIComponent(attemptId)}/receipt`);
+  }
+  if (name === 'getBillingSubscription') {
+    return apiFetch(config, options, 'GET', '/api/v1/billing/subscription');
+  }
+  throw Object.assign(new Error(`Unknown local billing tool: ${name}`), { exitCode: EXIT.USAGE });
+}
+
+async function handleMcpRequest(config, options, message) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) {
+    return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid JSON-RPC request.' } };
+  }
+
+  const id = message.id ?? null;
+  const method = message.method;
+  const isNotification = message.id === undefined;
+
+  if (method === 'notifications/initialized' || method === 'notifications/cancelled') return null;
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: message.params?.protocolVersion || '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'clipit', version: VERSION },
+      },
+    };
+  }
+  if (method === 'ping') return isNotification ? null : { jsonrpc: '2.0', id, result: {} };
+  if (isNotification) return null;
+
+  if (method === 'tools/list') {
+    const tools = await fetchMcpTools(config, options);
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        tools: tools.map((tool) => ({
+          name: tool.name,
+          description: mcpToolDescription(tool),
+          inputSchema: mcpToolInputSchema(tool),
+        })).filter((tool) => typeof tool.name === 'string' && tool.name.length > 0),
+      },
+    };
+  }
+
+  if (method === 'tools/call') {
+    const name = typeof message.params?.name === 'string' ? message.params.name : null;
+    if (!name) {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: 'tools/call requires params.name.' } };
+    }
+    const parameters = message.params?.arguments && typeof message.params.arguments === 'object' && !Array.isArray(message.params.arguments)
+      ? { ...message.params.arguments }
+      : {};
+    const confirmed = parameters.confirmed === true || parameters.confirm === true;
+    delete parameters.confirm;
+    if (confirmed) parameters.confirmed = true;
+    else delete parameters.confirmed;
+    let maxCredits = null;
+    try {
+      maxCredits = readMcpMaxCredits(parameters);
+    } catch (error) {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: error.message } };
+    }
+    const tools = await fetchMcpTools(config, options);
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool) {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown ClipIt tool: ${name}` } };
+    }
+    const localBillingTool = localMcpBillingTool(name);
+    const payload = {
+      functionName: name,
+      parameters,
+      confirmed,
+    };
+    if (localBillingTool) {
+      if (!confirmed && mcpToolRequiresConfirmation(localBillingTool, name)) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: mcpTextResult(await mcpConfirmationPayload(config, options, localBillingTool, name, parameters, payload, maxCredits)),
+        };
+      }
+      const result = await handleLocalMcpBillingTool(config, options, name, parameters);
+      return { jsonrpc: '2.0', id, result: mcpTextResult(result, Boolean(result?.error)) };
+    }
+    applyContextToAgentPayload(payload, parameters, await buildContext(config, options));
+    if (!confirmed && mcpToolRequiresConfirmation(tool, name)) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: mcpTextResult(await mcpConfirmationPayload(config, options, tool, name, parameters, payload, maxCredits)),
+      };
+    }
+    const maxCreditsResult = await mcpMaxCreditsResult(config, options, tool, name, parameters, payload, maxCredits);
+    if (maxCreditsResult) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: mcpTextResult(maxCreditsResult, true),
+      };
+    }
+    const result = normalizeAgentExecuteResult(await apiFetch(config, options, 'POST', '/api/v1/agent/execute', payload));
+    return { jsonrpc: '2.0', id, result: mcpTextResult(result, Boolean(result?.error)) };
+  }
+
+  return { jsonrpc: '2.0', id, error: { code: -32601, message: `Unsupported MCP method: ${method || ''}` } };
+}
+
+function mcpFrame(message) {
+  const body = JSON.stringify(redactDeep(message));
+  return `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
+}
+
+function mcpHeaderEnd(buffer) {
+  const crlf = buffer.indexOf('\r\n\r\n');
+  const lf = buffer.indexOf('\n\n');
+  if (crlf === -1) return lf === -1 ? null : { index: lf, length: 2 };
+  if (lf === -1) return { index: crlf, length: 4 };
+  return crlf < lf ? { index: crlf, length: 4 } : { index: lf, length: 2 };
+}
+
+function mcpLooksFramed(buffer) {
+  const prefix = 'Content-Length:';
+  const sample = buffer.toString('utf8', 0, Math.min(buffer.length, prefix.length));
+  if (prefix.startsWith(sample)) return buffer.length < prefix.length ? null : true;
+  return false;
+}
+
+function readMcpFrame(buffer) {
+  const headerEnd = mcpHeaderEnd(buffer);
+  if (!headerEnd) return { incomplete: true, buffer };
+  const header = buffer.subarray(0, headerEnd.index).toString('utf8');
+  const match = /^Content-Length:\s*(\d+)\s*$/im.exec(header);
+  if (!match) {
+    return {
+      message: null,
+      error: { code: -32600, message: 'Invalid MCP frame: missing Content-Length header.' },
+      buffer: Buffer.alloc(0),
+    };
+  }
+  const contentLength = Number(match[1]);
+  const bodyStart = headerEnd.index + headerEnd.length;
+  const bodyEnd = bodyStart + contentLength;
+  if (buffer.length < bodyEnd) return { incomplete: true, buffer };
+  const body = buffer.subarray(bodyStart, bodyEnd).toString('utf8');
+  try {
+    return {
+      message: JSON.parse(body),
+      buffer: buffer.subarray(bodyEnd),
+    };
+  } catch (error) {
+    return {
+      message: null,
+      error: { code: -32700, message: `Parse error: ${error.message}` },
+      buffer: buffer.subarray(bodyEnd),
+    };
+  }
+}
+
+async function respondToMcpMessage(config, options, message, send) {
+  try {
+    send(await handleMcpRequest(config, options, message));
+  } catch (error) {
+    send({
+      jsonrpc: '2.0',
+      id: message?.id ?? null,
+      error: {
+        code: -32000,
+        message: redact(error.message || String(error)),
+        data: redactDeep(compactObject({ status: error.status, requestId: error.requestId, details: error.data })),
+      },
+    });
+  }
+}
+
+async function runMcpStdio(config, options) {
+  let framed = null;
+  let frameBuffer = Buffer.alloc(0);
+  let lineBuffer = '';
+  const send = (message) => {
+    if (!message) return;
+    if (framed) {
+      process.stdout.write(mcpFrame(message));
+      return;
+    }
+    process.stdout.write(`${JSON.stringify(redactDeep(message))}\n`);
+  };
+
+  const sendTransportError = (error) => send({ jsonrpc: '2.0', id: null, error });
+  const processLineBuffer = async (flush = false) => {
+    let newlineIndex = lineBuffer.indexOf('\n');
+    while (newlineIndex !== -1) {
+      const line = lineBuffer.slice(0, newlineIndex).trim();
+      lineBuffer = lineBuffer.slice(newlineIndex + 1);
+      newlineIndex = lineBuffer.indexOf('\n');
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (error) {
+        sendTransportError({ code: -32700, message: `Parse error: ${error.message}` });
+        continue;
+      }
+      await respondToMcpMessage(config, options, message, send);
+    }
+    if (flush && lineBuffer.trim()) {
+      const line = lineBuffer.trim();
+      lineBuffer = '';
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (error) {
+        sendTransportError({ code: -32700, message: `Parse error: ${error.message}` });
+        return;
+      }
+      await respondToMcpMessage(config, options, message, send);
+    }
+  };
+
+  for await (const chunk of process.stdin) {
+    const chunkBuffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    let appendedToFrame = false;
+    if (framed === null) {
+      frameBuffer = Buffer.concat([frameBuffer, chunkBuffer]);
+      appendedToFrame = true;
+      const decision = mcpLooksFramed(frameBuffer);
+      if (decision === null) continue;
+      framed = decision;
+      if (!framed) {
+        lineBuffer += frameBuffer.toString('utf8');
+        frameBuffer = Buffer.alloc(0);
+        await processLineBuffer();
+        continue;
+      }
+    }
+
+    if (!framed) {
+      lineBuffer += chunkBuffer.toString('utf8');
+      await processLineBuffer();
+      continue;
+    }
+
+    if (framed && !appendedToFrame) {
+      frameBuffer = Buffer.concat([frameBuffer, chunkBuffer]);
+    }
+    while (framed) {
+      const parsed = readMcpFrame(frameBuffer);
+      frameBuffer = parsed.buffer;
+      if (parsed.incomplete) break;
+      if (parsed.error) {
+        sendTransportError(parsed.error);
+        continue;
+      }
+      await respondToMcpMessage(config, options, parsed.message, send);
+    }
+  }
+
+  if (framed === false) await processLineBuffer(true);
+}
+
+async function mcp(config, options, action) {
+  if (action && action !== 'stdio') {
+    throw Object.assign(new Error(`Unknown mcp command: ${action}`), { exitCode: EXIT.USAGE });
+  }
+  await runMcpStdio(config, options);
+}
+
 async function examples(options) {
   const data = {
     login: 'clipit login',
     installCodexSkill: 'clipit agent install codex',
     validate: 'clipit doctor --json',
-    importUrl: 'clipit videos import-url "https://www.youtube.com/watch?v=..." --json',
+    uploadVideo: 'clipit videos upload ./source.mp4 --confirm --json',
+    importUrl: 'clipit videos import-url "https://www.youtube.com/watch?v=..." --confirm --json',
     waitForJob: 'clipit jobs wait <jobId> --json',
     ask: 'clipit ask "Find the strongest clip in this video" --video-id <videoId>',
     approveWorkflow: 'clipit workflow approve <jobId> --approval-id <approvalId> --decision approved',
     waitForWorkflow: 'clipit workflow wait <jobId> --stream',
     setContext: 'clipit context use --video-id <videoId>',
-    suggestClips: 'clipit videos suggest-clips <videoId> --count 5 --json',
-    createClip: 'clipit clips create --video-id <videoId> --start 12 --end 42 --title "Strong hook" --json',
-    renderClip: 'clipit clips render <clipId> --aspect 9:16 --quality high --json',
+    mcp: 'clipit mcp stdio',
+    suggestClips: 'clipit videos suggest-clips <videoId> --count 5 --confirm --json',
+    createClip: 'clipit clips create --video-id <videoId> --start 12 --end 42 --title "Strong hook" --confirm --json',
+    renderClip: 'clipit clips render <clipId> --aspect 9:16 --quality high --confirm --json',
     creditsBalance: 'clipit credits balance --json',
+    billingCapabilities: 'clipit billing capabilities --json',
+    billingCatalog: 'clipit billing catalog --json',
+    billingX402Attempt: 'clipit billing create-attempt --product-key boost --provider x402_direct --confirm --json',
+    billingStripeX402Attempt: 'clipit billing create-attempt --product-key boost --provider stripe_x402 --confirm --json',
+    billingLinkAttempt: 'clipit billing create-attempt --product-key boost --provider stripe_mpp --confirm --json',
     analyticsOverview: 'clipit analytics overview --days 30 --json',
     exportClip: 'clipit exports start --clip-id <clipId> --confirm --json',
-    uploadAsset: 'clipit assets upload ./brand-logo.png --kind image --json',
+    uploadAsset: 'clipit assets upload ./brand-logo.png --kind image --confirm --json',
     thumbnail: 'clipit thumbnails generate --clip-id <clipId> --prompt "Expressive high-contrast thumbnail" --confirm --json',
     brollPlan: 'clipit broll plan <clipId> --count 3 --confirm --json',
     socialPost: 'clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json',
@@ -1945,11 +3050,16 @@ Rules:
 - If not connected, ask the user to run \`clipit login\` and approve the browser link.
 - Never ask the user to paste API keys into chat.
 - Use \`clipit skills list --json\` and \`clipit tools list --json\` to discover capability.
+- Use \`clipit mcp stdio\` when an MCP-compatible client can launch local stdio servers; it speaks standard \`Content-Length\` framed JSON-RPC.
 - Prefer friendly commands such as \`clipit videos list --json\`, \`clipit clips list --json\`, \`clipit credits balance --json\`, and \`clipit jobs wait <jobId> --json\`.
 - Use \`clipit ask "..."\` for natural-language Clippy workflows, and \`clipit workflow wait <jobId> --json\` or \`clipit workflow approve <jobId> --approval-id <id>\` for workflow follow-through.
+- Use \`clipit ask "..." --auto-confirm-costly\` only when the human has asked you to work autonomously on ClipIt-only cost-spending tasks. It never authorizes social publishing/scheduling or destructive actions.
 - Use \`clipit run <functionName> --params @file.json --json\` for exact Clippy tools.
 - Treat paid generation, publishing, deletion, broad mutation, and \`requiresConfirmation\` responses as user approval checkpoints.
 - Treat exit code 13 as insufficient credits or an API key spend-limit block; top up billing or adjust the key's spend limit in ClipIt Settings.
+- When credits are insufficient, discover payment rails with \`clipit billing capabilities --json\` and \`clipit billing catalog --json\`.
+- Only create direct x402, Stripe-managed x402, or Stripe Link/SPT payment attempts after explicit human approval or a configured budget policy: \`clipit billing create-attempt --product-key <key> --provider x402_direct|stripe_x402|stripe_mpp --confirm --json\`.
+- Credits from subscriptions and top-ups stack; paid features are credit-gated, so verify the payment receipt or balance before running paid ClipIt tools.
 - Use \`clipit open clip <id>\` when the user should review work in ClipIt.
 - Use \`clipit context use --video-id <id>\` or \`clipit context use --clip-id <id>\` to persist the current target for later commands.
 - Do not write API keys into this skill file or any project files.
@@ -1961,24 +3071,32 @@ clipit auth status --json
 clipit skills list --json
 clipit tools list --json
 clipit tools describe <functionName> --json
+clipit mcp stdio
 clipit ask "Find the strongest clip in this video" --video-id <videoId> --json
 clipit workflow wait <jobId> --stream
 clipit videos list --json
-clipit videos import-url "https://example.com/video" --json
+clipit videos upload ./source.mp4 --confirm --json
+clipit videos import-url "https://example.com/video" --confirm --json
 clipit videos transcript <videoId> --json
-clipit videos suggest-clips <videoId> --count 5 --json
+clipit videos suggest-clips <videoId> --count 5 --confirm --json
 clipit clips list --json
-clipit clips create --video-id <videoId> --start 12 --end 42 --title "Hook" --json
-clipit clips render <clipId> --aspect 9:16 --quality high --json
+clipit clips create --video-id <videoId> --start 12 --end 42 --title "Hook" --confirm --json
+clipit clips render <clipId> --aspect 9:16 --quality high --confirm --json
 clipit jobs wait <jobId> --stream
 clipit credits balance --json
 clipit credits usage --json
 clipit credits estimate --operation-type transcription --provider deepgram --metrics @metrics.json --json
+clipit billing capabilities --json
+clipit billing catalog --json
+clipit billing create-attempt --product-key boost --provider x402_direct --confirm --json
+clipit billing create-attempt --product-key boost --provider stripe_x402 --confirm --json
+clipit billing create-attempt --product-key boost --provider stripe_mpp --confirm --json
+clipit billing receipt <attemptId> --json
 clipit analytics overview --days 30 --json
 clipit exports start --clip-id <clipId> --confirm --json
 clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --json
 clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json
-clipit run renderClipWithRemotion --clip-id <clipId> --params @params.json --json
+clipit run renderClipWithRemotion --clip-id <clipId> --params @params.json --confirm --json
 \`\`\`
 
 Common workflow:
@@ -1992,6 +3110,28 @@ Agent target: ${agent}
 `;
 }
 
+function mcpSkillAddendum() {
+  return [
+    '## MCP Stdio Bridge',
+    '- If your agent runtime supports MCP stdio servers, prefer launching `clipit mcp stdio` from the user\'s machine instead of manually shelling every command.',
+    '- The bridge uses the authenticated CLI profile, speaks standard `Content-Length` framed JSON-RPC over stdio, and exposes the same live tools as `clipit tools list --json` / `GET /api/v1/agent/tools`.',
+    '- `tools/call` delegates to `/api/v1/agent/execute`, inherits the active CLI context from `clipit context use`, and preserves confirmation gates for paid generation, publishing, deletion, export, and other mutating calls.',
+    '- The bridge also exposes local billing discovery tools: `getPaymentCapabilities`, `getBillingCatalog`, `createPaymentAttempt`, `getPaymentAttempt`, `getPaymentReceipt`, and `getBillingSubscription`.',
+    '- `createPaymentAttempt` returns a payment URL for direct x402, Stripe-managed x402, or Stripe MPP/Link SPT settlement and requires `confirmed:true`; do not retry it until the human approves the product, amount, rail, and budget policy.',
+    '- If the MCP client cannot launch local commands, fall back to the CLI/API commands above.',
+  ].join('\n');
+}
+
+function withLocalCliSkillAddenda(markdown) {
+  const addenda = [];
+  let next = String(markdown || '');
+  if (!/clipit\s+mcp\s+stdio/i.test(next) && !/MCP Stdio Bridge/i.test(next)) {
+    next = `${next.trimEnd()}\n\n${mcpSkillAddendum()}\n`;
+    addenda.push('mcp-stdio-bridge');
+  }
+  return { markdown: next, addenda };
+}
+
 function fallbackSkillResult(target, reason) {
   const generatedAt = new Date().toISOString();
   return {
@@ -2041,10 +3181,14 @@ async function resolveAgentSkill(config, options, target) {
     });
   }
 
+  const augmented = withLocalCliSkillAddenda(response.markdown);
   return {
-    markdown: response.markdown,
+    markdown: augmented.markdown,
     source: 'server',
-    meta: response.meta,
+    meta: compactObject({
+      ...response.meta,
+      localCliAddenda: augmented.addenda.length ? augmented.addenda : undefined,
+    }),
   };
 }
 
@@ -2065,6 +3209,7 @@ function agentSkillSidecar(target, skill) {
     target,
     source: skill.source,
     generatedAt: skill.meta?.generatedAt,
+    markdownHash: hashText(skill.markdown),
     serverMeta: skill.source === 'server' ? skill.meta : undefined,
     fallbackReason: skill.fallbackReason,
   });
@@ -2088,7 +3233,11 @@ function agentInstallDir(target, options) {
 async function installedAgentStatus(target, options) {
   const baseDir = agentInstallDir(target, options);
   try {
-    const stat = await fs.stat(path.join(baseDir, 'SKILL.md'));
+    const skillPath = path.join(baseDir, 'SKILL.md');
+    const [stat, markdown] = await Promise.all([
+      fs.stat(skillPath),
+      fs.readFile(skillPath, 'utf8'),
+    ]);
     const sidecar = await readAgentSkillMeta(baseDir);
     return {
       target,
@@ -2098,6 +3247,7 @@ async function installedAgentStatus(target, options) {
       skillSource: sidecar?.source || 'unknown',
       generatedAt: sidecar?.generatedAt || null,
       fallbackReason: sidecar?.fallbackReason || null,
+      markdownHash: sidecar?.markdownHash || hashText(markdown),
       serverMeta: sidecar?.serverMeta || null,
     };
   } catch {
@@ -2105,6 +3255,24 @@ async function installedAgentStatus(target, options) {
   }
 }
 
+function agentFreshnessReason(status, currentSkill) {
+  const currentMeta = currentSkill.source === 'server' ? currentSkill.meta : null;
+  if (status.skillSource !== currentSkill.source) {
+    return `installed source ${status.skillSource || 'unknown'} differs from current source ${currentSkill.source}`;
+  }
+  if (status.serverMeta?.toolCount !== undefined
+    && currentMeta?.toolCount !== undefined
+    && status.serverMeta.toolCount !== currentMeta.toolCount) {
+    return `installed tool count ${status.serverMeta.toolCount} differs from current tool count ${currentMeta.toolCount}`;
+  }
+  if (status.serverMeta?.skillCount !== undefined
+    && currentMeta?.skillCount !== undefined
+    && status.serverMeta.skillCount !== currentMeta.skillCount) {
+    return `installed skill count ${status.serverMeta.skillCount} differs from current skill count ${currentMeta.skillCount}`;
+  }
+  return 'installed skill content differs from current generated instructions';
+}
+
 async function agent(config, options, action, args) {
   const target = args[0] || 'generic';
   const baseDir = agentInstallDir(target, options);
@@ -2121,12 +3289,41 @@ async function agent(config, options, action, args) {
   }
   if (action === 'doctor') {
     const status = await installedAgentStatus(target, options);
+    const hasCredential = Boolean(getApiKey(config, options));
     status.cli = {
       version: VERSION,
       configPath: configPath(),
       profile: profileName(config, options),
-      hasCredential: Boolean(getApiKey(config, options)),
+      hasCredential,
     };
+    if (status.installed) {
+      if (!hasCredential) {
+        status.upToDate = null;
+        status.stale = null;
+        status.freshnessError = 'Cannot verify installed skill freshness without credentials.';
+      } else {
+        const currentSkill = await resolveAgentSkill(config, options, target);
+        status.latest = compactObject({
+          skillSource: currentSkill.source,
+          generatedAt: currentSkill.meta?.generatedAt || null,
+          serverMeta: currentSkill.source === 'server' ? currentSkill.meta : undefined,
+          fallbackReason: currentSkill.fallbackReason,
+        });
+        if (currentSkill.source === 'fallback') {
+          status.upToDate = null;
+          status.stale = null;
+          status.freshnessError = `Cannot verify installed skill freshness: ${currentSkill.fallbackReason || 'current instructions unavailable'}`;
+        } else {
+          const currentHash = hashText(currentSkill.markdown);
+          status.upToDate = status.markdownHash === currentHash;
+          status.stale = !status.upToDate;
+          if (status.stale) {
+            status.staleReason = agentFreshnessReason(status, currentSkill);
+            status.updateCommand = `clipit agent update ${target}`;
+          }
+        }
+      }
+    }
     output(status, options);
     return;
   }
@@ -2160,6 +3357,10 @@ async function main() {
   const config = await readConfig();
   const [command, subcommand, ...rest] = positionals;
 
+  if (options.version === true || options.version === 'true') {
+    output({ version: VERSION }, options);
+    return;
+  }
   if (!command || options.help) {
     console.log(usage());
     return;
@@ -2182,11 +3383,13 @@ async function main() {
   if (command === 'tools' && subcommand === 'describe') return describeTool(config, options, rest[0]);
   if (command === 'ask') return askWorkflow(config, options, [subcommand, ...rest]);
   if (command === 'workflow') return workflow(config, options, subcommand, rest);
+  if (command === 'mcp') return mcp(config, options, subcommand);
   if (command === 'run') return runTool(config, options, subcommand);
   if (command === 'videos') return videos(config, options, subcommand, rest);
   if (command === 'clips') return clips(config, options, subcommand, rest);
   if (command === 'jobs') return jobs(config, options, subcommand, rest);
   if (command === 'credits') return credits(config, options, subcommand, rest);
+  if (command === 'billing') return billing(config, options, subcommand, rest);
   if (command === 'analytics') return analytics(config, options, subcommand, rest);
   if (command === 'exports') return exportsCommand(config, options, subcommand, rest);
   if (command === 'assets') return assets(config, options, subcommand, rest);
@@ -2235,4 +3438,4 @@ if (await isDirectRun()) {
   main().catch(handleMainError);
 }
 
-export { main, redact };
+export { main, redact, clipCostLabel, handleMcpRequest };