@socialseal/cli 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.1.12 - 2026-06-23
+
+- Expose Asset Studio and video production tool surfaces through CLI discovery/schema output.
+- Add category-filtered tool discovery for users and agents.
+
+## 0.1.11 - 2026-06-12
+
+- Add ad hoc public video URL analysis parity for queue and extract workflows, including `--url` and `--allow-untracked` support.
+
 ## 0.1.10 - 2026-06-10
 
 - Clarify ranked search exports now include publish/observed dates and scoped tracked-search resurfacing history fields when the backend export template is deployed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -144,7 +144,95 @@ const KNOWN_TOOLS = [
     transport: 'post_edge_function',
     workspaceScoped: true,
     knownLocalDevState: 'enabled',
-    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items; videoId means video_uid or platform-native video id, not a tracking item id.',
+    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items and public URL items with allowUntracked=true; videoId means video_uid or platform-native video id, not a tracking item id.',
+  },
+  {
+    name: 'vnext-clips-read',
+    category: 'asset-studio',
+    description: 'List workspace clip-library items and optionally sign selected source videos.',
+    objectType: 'workspace_clip',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-clips-create',
+    category: 'asset-studio',
+    description: 'Create signed clip upload targets and finalize uploaded clip metadata.',
+    objectType: 'workspace_clip',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['create', 'finalize'],
+    notes: 'The create action returns signed upload URLs; upload bytes to storage before calling finalize.',
+  },
+  {
+    name: 'vnext-clip-shot-mappings-read',
+    category: 'asset-studio',
+    description: 'Read clip-to-blueprint shot mappings for Asset Studio.',
+    objectType: 'clip_shot_mapping',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-clip-shot-mappings-write',
+    category: 'asset-studio',
+    description: 'Upsert or delete clip-to-blueprint shot mappings for Asset Studio.',
+    objectType: 'clip_shot_mapping',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['upsert', 'delete'],
+  },
+  {
+    name: 'vnext-generated-assets-read',
+    category: 'asset-studio',
+    description: 'List generated rough cuts for a blueprint or read one generated asset.',
+    objectType: 'generated_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'detail'],
+  },
+  {
+    name: 'vnext-generated-asset-create',
+    category: 'asset-studio',
+    description: 'Create a generated rough-cut asset from an edit spec.',
+    objectType: 'generated_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-generated-asset-optimize',
+    category: 'asset-studio',
+    description: 'Optimize a generated asset or create a new revision.',
+    objectType: 'generated_asset_revision',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['optimize', 'create-revision'],
+  },
+  {
+    name: 'vnext-generated-asset-export',
+    category: 'asset-studio',
+    description: 'Export a generated rough cut as FCPXML.',
+    objectType: 'generated_asset_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-generated-asset-share',
+    category: 'asset-studio',
+    description: 'Create, read, or revoke generated-asset share links.',
+    objectType: 'generated_asset_share',
+    transport: 'post_edge_function',
+    workspaceScoped: false,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['create', 'read', 'revoke'],
+    notes: 'create/revoke require workspaceId in the body; read uses shareToken and does not require workspace scope.',
   },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   {
@@ -218,7 +306,34 @@ const KNOWN_TOOLS = [
   { name: 'vnext-blueprints-create', category: 'vnext', description: 'Create a vNext blueprint from grounded evidence.' },
   { name: 'vnext-blueprints-generate', category: 'vnext', description: 'Generate a vNext blueprint from workspace opportunity data.' },
   { name: 'vnext-blueprints-read', category: 'vnext', description: 'Read vNext blueprint history and specific versions.' },
+  {
+    name: 'vnext-blueprints-shots-read',
+    category: 'video-production',
+    description: 'Read shot-lift and pinned shot assets for a blueprint.',
+    objectType: 'blueprint_shot_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-blueprints-shots-refresh',
+    category: 'video-production',
+    description: 'Queue a refresh for blueprint shot assets.',
+    objectType: 'blueprint_shots_job',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
   { name: 'vnext-briefs-create', category: 'vnext', description: 'Create a vNext brief record.' },
+  {
+    name: 'vnext-briefs-export',
+    category: 'video-production',
+    description: 'Export a generated vNext brief as markdown.',
+    objectType: 'vnext_brief_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
   { name: 'vnext-briefs-generate', category: 'vnext', description: 'Generate a vNext brief from a blueprint or opportunity.' },
   { name: 'vnext-briefs-read', category: 'vnext', description: 'Read generated vNext briefs and version history.' },
   { name: 'vnext-intents', category: 'vnext', description: 'List, create, update, or delete vNext intents.' },
@@ -258,6 +373,23 @@ const TOOL_SCHEMA_HINTS = {
           jobId: '11111111-1111-4111-8111-111111111111',
         },
       },
+      {
+        action: 'status',
+        required: ['action=status', 'workspaceId or --workspace-id', 'items[] with videoUid or platformVideoId'],
+        optional: ['includeRawAnalysis'],
+        notes: 'Status polling is read-only and does not accept URL items; use videoUid or platformVideoId returned by the initial URL extraction response.',
+        example: {
+          action: 'status',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          items: [
+            {
+              videoUid: '11111111-1111-4111-8111-111111111111',
+            },
+          ],
+          includeAssets: false,
+          includeSourceVideo: false,
+        },
+      },
     ],
     cliExamples: [
       'socialseal tools call --function agent-tool-jobs --body \'{"action":"start","toolName":"search_videos","payload":{"query":"best africa safari itinerary","platform":"tiktok","region":"IN"}}\'',
@@ -376,6 +508,369 @@ const TOOL_SCHEMA_HINTS = {
       'socialseal tools call --function get-google-ai-search-results --body \'{"runId":6809,"includeCitations":true,"limit":10}\'',
     ],
   },
+  'tracked-video-extract': {
+    summary: 'Extract assets and queue/read analysis for tracked identifiers or ad hoc public video URLs.',
+    operations: [
+      {
+        action: 'extract',
+        required: ['workspaceId or --workspace-id', 'items[] with exactly one selector'],
+        optional: [
+          'items[].searchResultId',
+          'items[].videoId',
+          'items[].videoUid',
+          'items[].platformVideoId',
+          'items[].url',
+          'allowUntracked',
+          'ensureAnalysis',
+          'includeAssets',
+          'includeSourceVideo',
+          'frameStrategy',
+          'frameCount',
+          'signedUrlSeconds',
+        ],
+        notes: 'URL items require request-level allowUntracked:true. Supported selectors are url, searchResultId, videoId, videoUid, or platformVideoId.',
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          allowUntracked: true,
+          ensureAnalysis: true,
+          items: [
+            {
+              url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+            },
+          ],
+        },
+      },
+      {
+        action: 'queue-analysis',
+        required: ['workspaceId or --workspace-id', 'items[] with exactly one selector'],
+        optional: ['allowUntracked for URL items', 'queueOnly', 'includeRawAnalysis'],
+        notes: 'Set ensureAnalysis:true and queueOnly:true to enqueue analysis without asset URL generation.',
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          allowUntracked: true,
+          ensureAnalysis: true,
+          queueOnly: true,
+          includeAssets: false,
+          items: [
+            {
+              url: 'https://www.tiktok.com/@creator/video/7348293840000000000',
+            },
+          ],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal video extract --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --allow-untracked --wait --out-dir ./video-assets --workspace-id <workspace-uuid>',
+      'socialseal video queue-analysis --url https://www.tiktok.com/@creator/video/7348293840000000000 --allow-untracked --wait --workspace-id <workspace-uuid>',
+      'socialseal video extract --video-uid <video-uuid> --wait --workspace-id <workspace-uuid>',
+      'socialseal tools call --function tracked-video-extract --workspace-id <workspace-uuid> --body \'{"allowUntracked":true,"items":[{"url":"https://www.instagram.com/reel/SHORTCODE/"}]}\'',
+    ],
+  },
+  'vnext-clips-read': {
+    summary: 'List Asset Studio clip-library items and optionally sign selected video URLs.',
+    operations: [
+      {
+        action: 'list',
+        required: ['workspaceId or --workspace-id'],
+        optional: ['videoClipIds[] to include signed source video URLs'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          videoClipIds: ['11111111-1111-4111-8111-111111111111'],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clips-read --workspace-id <workspace-uuid> --body \'{"videoClipIds":["<clip-uuid>"]}\'',
+    ],
+  },
+  'vnext-clips-create': {
+    summary: 'Create signed upload targets for clips and finalize uploaded clip metadata.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'workspaceId or --workspace-id', 'fileName', 'mimeType'],
+        optional: [],
+        example: {
+          action: 'create',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          fileName: 'hero-shot.mp4',
+          mimeType: 'video/mp4',
+        },
+      },
+      {
+        action: 'finalize',
+        required: ['action=finalize', 'workspaceId or --workspace-id', 'clipId', 'fileName', 'storagePath', 'mimeType', 'sizeBytes', 'rightsAttested=true'],
+        optional: ['durationSeconds', 'width', 'height', 'posterPath'],
+        example: {
+          action: 'finalize',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          clipId: '11111111-1111-4111-8111-111111111111',
+          fileName: 'hero-shot.mp4',
+          storagePath: 'workspace-00000000-0000-4000-8000-000000000000/11111111-1111-4111-8111-111111111111.mp4',
+          mimeType: 'video/mp4',
+          sizeBytes: 1048576,
+          rightsAttested: true,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body \'{"action":"create","fileName":"hero-shot.mp4","mimeType":"video/mp4"}\'',
+      'socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body @clip-finalize.json',
+    ],
+  },
+  'vnext-clip-shot-mappings-read': {
+    summary: 'Read Asset Studio clip-to-shot mappings for a blueprint.',
+    operations: [
+      {
+        action: 'read',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clip-shot-mappings-read --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-clip-shot-mappings-write': {
+    summary: 'Upsert or delete Asset Studio clip-to-shot mappings.',
+    operations: [
+      {
+        action: 'upsert',
+        required: ['action=upsert', 'workspaceId or --workspace-id', 'blueprintId', 'panelId', 'clipId'],
+        optional: ['source (suggested|override)', 'score'],
+        example: {
+          action: 'upsert',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          panelId: 'panel-1',
+          clipId: '11111111-1111-4111-8111-111111111111',
+          source: 'override',
+        },
+      },
+      {
+        action: 'delete',
+        required: ['action=delete', 'workspaceId or --workspace-id', 'blueprintId', 'panelId'],
+        optional: [],
+        example: {
+          action: 'delete',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          panelId: 'panel-1',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clip-shot-mappings-write --workspace-id <workspace-uuid> --body \'{"action":"upsert","blueprintId":"<blueprint-uuid>","panelId":"panel-1","clipId":"<clip-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-assets-read': {
+    summary: 'List generated rough cuts for a blueprint or read one generated asset.',
+    operations: [
+      {
+        action: 'list',
+        required: ['action=list', 'workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          action: 'list',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+      {
+        action: 'detail',
+        required: ['action=detail', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'detail',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body \'{"action":"list","blueprintId":"<blueprint-uuid>"}\'',
+      'socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body \'{"action":"detail","assetId":"<asset-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-asset-create': {
+    summary: 'Create a generated rough cut from an Asset Studio edit spec.',
+    operations: [
+      {
+        action: 'create',
+        required: ['workspaceId or --workspace-id', 'blueprintId', 'title', 'editSpec'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          title: 'Homepage rough cut',
+          editSpec: {
+            version: 1,
+            fps: 30,
+            width: 1080,
+            height: 1920,
+            totalDurationSeconds: 3,
+            shots: [
+              {
+                panelId: 'panel-1',
+                clipId: '11111111-1111-4111-8111-111111111111',
+                title: 'Opening hook',
+                kind: 'hook',
+                shotLabel: 'Hero exterior',
+                sourceStartSeconds: 0,
+                durationSeconds: 3,
+                evidenceIds: [],
+              },
+            ],
+          },
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-create --workspace-id <workspace-uuid> --body @edit-spec.json',
+    ],
+  },
+  'vnext-generated-asset-optimize': {
+    summary: 'Optimize a generated asset or create a new revision.',
+    operations: [
+      {
+        action: 'optimize',
+        required: ['action=optimize', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'optimize',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+      {
+        action: 'create-revision',
+        required: ['action=create-revision', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'create-revision',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-optimize --workspace-id <workspace-uuid> --body \'{"action":"optimize","assetId":"<asset-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-asset-export': {
+    summary: 'Export a generated rough cut as FCPXML.',
+    operations: [
+      {
+        action: 'export',
+        required: ['workspaceId or --workspace-id', 'assetId'],
+        optional: ['format=fcpxml'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+          format: 'fcpxml',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-export --workspace-id <workspace-uuid> --body \'{"assetId":"<asset-uuid>","format":"fcpxml"}\'',
+    ],
+  },
+  'vnext-generated-asset-share': {
+    summary: 'Create, read, or revoke generated rough-cut share links.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'workspaceId', 'assetId'],
+        optional: ['ttlSeconds', 'shareBaseUrl'],
+        example: {
+          action: 'create',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+          ttlSeconds: 604800,
+        },
+      },
+      {
+        action: 'read',
+        required: ['action=read', 'shareToken'],
+        optional: [],
+        example: {
+          action: 'read',
+          shareToken: '0123456789abcdef0123456789abcdef',
+        },
+      },
+      {
+        action: 'revoke',
+        required: ['action=revoke', 'workspaceId', 'shareLinkId'],
+        optional: [],
+        example: {
+          action: 'revoke',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          shareLinkId: '44444444-4444-4444-8444-444444444444',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-share --body \'{"action":"create","workspaceId":"<workspace-uuid>","assetId":"<asset-uuid>"}\'',
+      'socialseal tools call --function vnext-generated-asset-share --body \'{"action":"read","shareToken":"<share-token>"}\'',
+    ],
+  },
+  'vnext-blueprints-shots-read': {
+    summary: 'Read blueprint shot-lift rows and pinned shot assets with signed URLs.',
+    operations: [
+      {
+        action: 'read',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: ['signedUrlSeconds'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          signedUrlSeconds: 3600,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-blueprints-shots-read --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-blueprints-shots-refresh': {
+    summary: 'Queue a refresh for blueprint shot assets.',
+    operations: [
+      {
+        action: 'refresh',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-blueprints-shots-refresh --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-briefs-export': {
+    summary: 'Export the latest or selected generated vNext brief as markdown.',
+    operations: [
+      {
+        action: 'export',
+        required: ['workspaceId or --workspace-id', 'opportunityKey'],
+        optional: ['version'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          opportunityKey: 'opportunity-key',
+          version: 1,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-briefs-export --workspace-id <workspace-uuid> --body \'{"opportunityKey":"<opportunity-key>"}\'',
+    ],
+  },
   'group-management': {
     summary: 'Manage single-platform tracking groups and memberships.',
     operations: [
@@ -469,6 +964,18 @@ function buildToolRegistry() {
   });
 }
 
+function filterToolRegistry(tools, category) {
+  const normalizedCategory = trimString(category).toLowerCase();
+  const filtered = normalizedCategory
+    ? tools.filter((tool) => trimString(tool.category).toLowerCase() === normalizedCategory)
+    : tools;
+  return [...filtered].sort((a, b) => {
+    const categoryCompare = trimString(a.category).localeCompare(trimString(b.category));
+    if (categoryCompare !== 0) return categoryCompare;
+    return trimString(a.name).localeCompare(trimString(b.name));
+  });
+}
+
 function getConfigPath() {
   return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
 }
@@ -751,6 +1258,7 @@ function inferExtension(urlValue, contentType, fallback = '.bin') {
 function normalizeVideoExtractBody(body) {
   const normalized = { ...body };
   const hasInlineIdentifier =
+    normalized.url !== undefined ||
     normalized.videoId !== undefined ||
     normalized.searchResultId !== undefined ||
     normalized.videoUid !== undefined ||
@@ -758,12 +1266,14 @@ function normalizeVideoExtractBody(body) {
 
   if (!Array.isArray(normalized.items) && hasInlineIdentifier) {
     normalized.items = [{
+      url: normalized.url,
       videoId: normalized.videoId,
       searchResultId: normalized.searchResultId,
       videoUid: normalized.videoUid,
       platformVideoId: normalized.platformVideoId,
       platformId: normalized.platformId,
     }];
+    delete normalized.url;
     delete normalized.videoId;
     delete normalized.searchResultId;
     delete normalized.videoUid;
@@ -774,6 +1284,11 @@ function normalizeVideoExtractBody(body) {
   return normalized;
 }
 
+function hasUrlVideoItems(body) {
+  const items = Array.isArray(body?.items) ? body.items : [];
+  return items.some((item) => typeof item?.url === 'string' && item.url.trim().length > 0);
+}
+
 function buildVideoExtractBody(opts, workspaceId) {
   const parsed = opts.body
     ? ensureJsonObject(parseJsonInput(opts.body, { label: 'body' }), 'body')
@@ -782,6 +1297,7 @@ function buildVideoExtractBody(opts, workspaceId) {
 
   if (!Array.isArray(normalized.items) || normalized.items.length === 0) {
     const inlineItem = stripUndefinedEntries({
+      url: trimString(opts.url) || undefined,
       videoId: trimString(opts.videoId) || undefined,
       searchResultId: opts.searchResultId !== undefined
         ? coercePositiveInteger(opts.searchResultId, 'searchResultId')
@@ -791,10 +1307,10 @@ function buildVideoExtractBody(opts, workspaceId) {
     });
 
     if (Object.keys(inlineItem).length === 0) {
-      throw new CliError('Provide --body or one of --video-id, --video-uid, --platform-video-id, or --search-result-id.', {
+      throw new CliError('Provide --body or one of --url, --video-id, --video-uid, --platform-video-id, or --search-result-id.', {
         code: 'MISSING_ARGUMENT',
         exitCode: EXIT_CODES.USAGE,
-        hint: '--video-id accepts a video_uid or platform video id. It does not accept tracking item ids.',
+        hint: '--url requires --allow-untracked. --video-id accepts a video_uid or platform video id; it does not accept tracking item ids.',
       });
     }
 
@@ -811,6 +1327,17 @@ function buildVideoExtractBody(opts, workspaceId) {
   }
 
   const nextBody = { ...bodyWithWorkspace };
+  if (opts.allowUntracked === true) {
+    nextBody.allowUntracked = true;
+  }
+  if (hasUrlVideoItems(nextBody) && nextBody.allowUntracked !== true) {
+    throw new CliError('URL video analysis requires --allow-untracked or allowUntracked:true in --body.', {
+      code: 'ALLOW_UNTRACKED_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --allow-untracked for ad hoc public URL analysis. Existing tracked identifier flows do not need this flag.',
+    });
+  }
+
   if (opts.wait) {
     nextBody.ensureAnalysis = true;
   } else if (opts.ensureAnalysis === true) {
@@ -868,11 +1395,60 @@ function buildVideoQueueBody(opts, workspaceId) {
 function hasPendingVideoExtractResults(payload) {
   const results = Array.isArray(payload?.results) ? payload.results : [];
   return results.some((result) => {
-    const status = String(result?.analysis?.status || '').trim().toLowerCase();
-    return status === 'pending' || status === 'processing';
+    const itemStatus = String(result?.status || '').trim().toLowerCase();
+    const analysisStatus = String(
+      result?.analysis?.normalizedStatus || result?.analysis?.status || '',
+    ).trim().toLowerCase();
+    const status = itemStatus || analysisStatus;
+    return ACTIVE_STATUS_VALUES.has(status);
   });
 }
 
+function buildVideoExtractStatusPollBody(originalBody, payload) {
+  const results = Array.isArray(payload?.results) ? payload.results : [];
+  const items = results
+    .map((result) => {
+      const resolved = isJsonObject(result?.resolvedVideo)
+        ? result.resolvedVideo
+        : (isJsonObject(result?.resolved) ? result.resolved : {});
+      const videoUid = trimString(resolved.videoUid || resolved.video_uid);
+      if (videoUid) return { videoUid };
+      const platformVideoId = trimString(
+        resolved.platformVideoId || resolved.platform_video_id,
+      );
+      if (platformVideoId) {
+        const item = { platformVideoId };
+        if (Number.isInteger(resolved.platformId)) {
+          item.platformId = resolved.platformId;
+        } else if (Number.isInteger(resolved.platform_id)) {
+          item.platformId = resolved.platform_id;
+        }
+        return item;
+      }
+      const request = isJsonObject(result?.request) ? result.request : null;
+      if (!request || request.url) return null;
+      return request;
+    })
+    .filter(Boolean);
+
+  if (items.length === 0) {
+    const originalHasUrl = Array.isArray(originalBody.items) &&
+      originalBody.items.some((item) => Boolean(item?.url));
+    if (originalHasUrl) return null;
+    return originalBody;
+  }
+
+  return {
+    workspaceId: originalBody.workspaceId,
+    action: 'status',
+    items,
+    includeRawAnalysis: originalBody.includeRawAnalysis === true,
+    includeAssets: false,
+    includeSourceVideo: false,
+    ensureAnalysis: false,
+  };
+}
+
 async function downloadAssetToFile({ url, outDir, stem, timeoutMs }) {
   const response = await fetchWithTimeout(url, {
     method: 'GET',
@@ -1020,6 +1596,23 @@ function resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) {
   return fallbackWorkspaceId || null;
 }
 
+function isGeneratedAssetShareScopedAction(functionName, payload) {
+  if (functionName !== 'vnext-generated-asset-share' || !isJsonObject(payload)) {
+    return false;
+  }
+  const action = trimString(payload.action).toLowerCase();
+  return action === 'create' || action === 'revoke';
+}
+
+function shouldRequireToolWorkspace(functionName, payload) {
+  const tool = getKnownTool(functionName);
+  const category = trimString(tool?.category).toLowerCase();
+  return (
+    Boolean(tool?.workspaceScoped) &&
+      (category === 'asset-studio' || category === 'video-production')
+  ) || isGeneratedAssetShareScopedAction(functionName, payload);
+}
+
 function isUuidLike(value) {
   return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.trim());
 }
@@ -3612,6 +4205,26 @@ async function handleToolsCall(opts) {
     });
   }
 
+  const scopedPayload = isJsonObject(translated.normalizedPayload)
+    ? translated.normalizedPayload
+    : (isJsonObject(translated.body) ? translated.body : payload);
+  const hasSpecialWorkspaceHandling = new Set([
+    'group-management',
+    'export_tracking_data',
+    'tracked-video-extract',
+  ]).has(opts.function);
+  if (!hasSpecialWorkspaceHandling && shouldRequireToolWorkspace(opts.function, scopedPayload)) {
+    requireWorkspaceSelection(effectiveWorkspaceId, {
+      label: opts.function,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, include workspaceId in the body, or configure a default workspace.',
+    });
+    emitWorkspaceSelectionNotice(opts, {
+      workspaceId: effectiveWorkspaceId,
+      source: effectiveWorkspaceSource,
+      label: opts.function,
+    });
+  }
+
   emitTrackingCreateScopeWarning(
     isJsonObject(translated.normalizedPayload) ? trimString(translated.normalizedPayload.action).toLowerCase() : '',
     effectiveWorkspaceId,
@@ -3710,9 +4323,10 @@ async function handleToolsCall(opts) {
 }
 
 function handleToolsList(opts) {
-  const tools = buildToolRegistry();
+  const tools = filterToolRegistry(buildToolRegistry(), opts.category);
   const payload = {
     discovery: 'built_in_registry',
+    category: trimString(opts.category) || null,
     tools,
     note: STATIC_TOOL_REGISTRY_NOTE,
     schemaNote: STATIC_TOOL_SCHEMA_NOTE,
@@ -3724,6 +4338,9 @@ function handleToolsList(opts) {
   }
 
   process.stdout.write('[socialseal] Built-in tool registry\n');
+  if (payload.category) {
+    process.stdout.write(`[socialseal] Category filter: ${payload.category}\n`);
+  }
   process.stdout.write(`[socialseal] ${payload.note}\n`);
   process.stdout.write(`[socialseal] ${payload.schemaNote}\n`);
 
@@ -4448,13 +5065,13 @@ async function handleVideoExtract(opts) {
     method: 'POST',
   });
 
-  const requestOnce = async (remainingTimeoutMs) => {
+  const requestOnce = async (remainingTimeoutMs, requestBody = body) => {
     const res = await callApi({
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path,
       method: 'POST',
-      body,
+      body: requestBody,
       workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
@@ -4479,6 +5096,7 @@ async function handleVideoExtract(opts) {
   };
 
   let payload = await requestOnce(timeoutMs);
+  let pollBody = buildVideoExtractStatusPollBody(body, payload);
 
   if (opts.wait) {
     const pollIntervalMs = resolvePollIntervalMs(opts);
@@ -4497,7 +5115,16 @@ async function handleVideoExtract(opts) {
 
       emitInfo(opts, 'tracked-video-extract pending; polling for completion.');
       await sleep(Math.min(pollIntervalMs, remainingMs));
-      payload = await requestOnce(Math.max(1000, deadline - Date.now()));
+      if (!pollBody) {
+        throw new CliError('Cannot poll URL analysis without a resolved video identifier.', {
+          code: 'MISSING_RESOLVED_VIDEO_ID',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Retry without --wait, then poll with the returned videoUid or platformVideoId.',
+          details: truncateDetails(payload),
+        });
+      }
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()), pollBody);
+      pollBody = buildVideoExtractStatusPollBody(body, payload);
     }
   }
 
@@ -4536,13 +5163,13 @@ async function handleVideoQueueAnalysis(opts) {
     method: 'POST',
   });
 
-  const requestOnce = async (remainingTimeoutMs) => {
+  const requestOnce = async (remainingTimeoutMs, requestBody = body) => {
     const res = await callApi({
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path,
       method: 'POST',
-      body,
+      body: requestBody,
       workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
@@ -4567,6 +5194,7 @@ async function handleVideoQueueAnalysis(opts) {
   };
 
   let payload = await requestOnce(timeoutMs);
+  let pollBody = buildVideoExtractStatusPollBody(body, payload);
 
   if (opts.wait) {
     const pollIntervalMs = resolvePollIntervalMs(opts);
@@ -4585,7 +5213,16 @@ async function handleVideoQueueAnalysis(opts) {
 
       emitInfo(opts, 'tracked-video queue-analysis pending; polling for completion.');
       await sleep(Math.min(pollIntervalMs, remainingMs));
-      payload = await requestOnce(Math.max(1000, deadline - Date.now()));
+      if (!pollBody) {
+        throw new CliError('Cannot poll URL analysis without a resolved video identifier.', {
+          code: 'MISSING_RESOLVED_VIDEO_ID',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Retry without --wait, then poll with the returned videoUid or platformVideoId.',
+          details: truncateDetails(payload),
+        });
+      }
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()), pollBody);
+      pollBody = buildVideoExtractStatusPollBody(body, payload);
     }
   }
 
@@ -4819,6 +5456,7 @@ const tools = program.command('tools').description('Call edge functions directly
 tools
   .command('list')
   .description('List built-in tool registry entries')
+  .option('--category <name>', 'Filter tools by category')
   .option('--json', 'Emit machine-readable output')
   .option('--pretty', 'Pretty-print JSON')
   .option('--verbose', 'Show error details')
@@ -4967,12 +5605,14 @@ const video = program.command('video').description('Tracked video extraction wor
 
 video
   .command('queue-analysis')
-  .description('Queue video analysis for tracked videos or tracked search results')
+  .description('Queue video analysis for tracked videos, tracked search results, or ad hoc public URLs')
+  .option('--url <url>', 'Public TikTok, Instagram, or YouTube video URL (requires --allow-untracked)')
   .option('--video-id <id>', 'Tracked video identifier (video_uid first, then platform video id; not a tracking item id)')
   .option('--search-result-id <id>', 'Tracked search result id for a ranked result row')
   .option('--video-uid <id>', 'Canonical tracked video_uid')
   .option('--platform-video-id <id>', 'Platform-native video id')
   .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch queueing')
+  .option('--allow-untracked', 'Allow ad hoc public URL analysis for videos not already tracked')
   .option('--wait', 'Poll until queued/completing analyses settle')
   .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')
   .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
@@ -4986,12 +5626,14 @@ video
 
 video
   .command('extract')
-  .description('Resolve tracked videos/results into structured analysis plus reference assets')
+  .description('Resolve tracked videos/results or ad hoc public URLs into structured analysis plus reference assets')
+  .option('--url <url>', 'Public TikTok, Instagram, or YouTube video URL (requires --allow-untracked)')
   .option('--video-id <id>', 'Tracked video identifier (video_uid first, then platform video id; not a tracking item id)')
   .option('--search-result-id <id>', 'Tracked search result id for a ranked result row')
   .option('--video-uid <id>', 'Canonical tracked video_uid')
   .option('--platform-video-id <id>', 'Platform-native video id')
   .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch extraction')
+  .option('--allow-untracked', 'Allow ad hoc public URL analysis for videos not already tracked')
   .option('--ensure-analysis', 'Queue analysis when it is missing')
   .option('--wait', 'Poll until queued/completing analyses settle')
   .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')