@socialseal/cli 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.1.9 - 2026-05-13
+- Fail `group-management add_items` on backend partial failures, expected-count mismatches, and failed backend verification.
+- Add `data export-group-evidence` to route social ranked evidence and Google AI evidence to the right raw export template with metadata.
+- Add `data group-completeness` with backend-first completeness checks, manifest fallback, and refresh status visibility.
+- Harden `tools status --wait` terminal failure handling and empty group refresh guardrails.
+
 ## 0.1.8 - 2026-04-13
 - Increase default CLI timeout from 30s to 5m to reduce false timeout failures on heavy tool/export workflows.
 - Harden async `search-journey-run` polling to accept additional active/terminal status labels (`queued`, `in_progress`, `running`, `succeeded`, `error`) instead of failing on unexpected variants.

package/package.json

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

package/src/index.js

@@ -33,6 +33,8 @@ const ACTIVE_STATUS_VALUES = new Set(['queued', 'pending', 'processing', 'in_pro
 const TOOL_STATUS_KINDS = new Set(['auto', 'agent_job', 'google_ai_run', 'journey_run']);
 const REPORT_TYPE_SEARCH_RESULTS_ENRICHED = 'search_results_enriched';
 const EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW = 'tracking_ranked_videos_raw';
+const EXPORT_DATA_TEMPLATE_GOOGLE_AI_SEARCH_SUMMARIES_RAW = 'google_ai_search_summaries_raw';
+const PLATFORM_ID_GOOGLE_AI = 11;
 const SUPPORTED_EXPORT_REPORT_TYPES = [
   'keyword_universe',
   'cluster_insights',
@@ -59,6 +61,14 @@ const EXPORT_OPTIONS = [
     bestFor: 'SQL-like ranked-search datasets without using psql.',
     alias: 'socialseal data export-report --report-type search_results_enriched --format csv --payload @payload.json',
   },
+  {
+    id: 'group_evidence',
+    command: 'socialseal data export-group-evidence --group-id <id> --workspace-id <uuid>',
+    summary: 'Unified group evidence export that routes social groups and Google AI groups to the right raw export template.',
+    formats: ['csv'],
+    required: ['workspace id', '--group-id'],
+    bestFor: 'Automation that needs usable evidence without knowing whether the group is social ranked search or Google AI.',
+  },
   {
     id: 'report_templates',
     command: 'socialseal data export-report --report-type <type> --format <format> --payload @payload.json',
@@ -180,7 +190,7 @@ const KNOWN_TOOLS = [
     workspaceScoped: true,
     knownLocalDevState: 'disabled_by_default',
     actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh', 'list_items', 'add_item', 'group_add_item', 'add_items', 'group_add_items', 'remove_item', 'group_remove_item'],
-    notes: 'REST-style surface under /groups. `add_item`/`group_add_item` accepts an existing `item_id`; `add_items`/`group_add_items` accepts `item_ids` or item payloads for bulk membership adds. Always pass a workspace id or configure a default workspace so the backend does not fall back to the personal workspace.',
+    notes: 'REST-style surface under /groups. `add_item`/`group_add_item` accepts an existing `item_id`; `add_items`/`group_add_items` accepts `item_ids` or item payloads for bulk membership adds. `completeness` checks expected memberships and refresh queue visibility. Always pass a workspace id or configure a default workspace so the backend does not fall back to the personal workspace.',
   },
   {
     name: 'tracking',
@@ -366,6 +376,68 @@ const TOOL_SCHEMA_HINTS = {
       'socialseal tools call --function get-google-ai-search-results --body \'{"runId":6809,"includeCitations":true,"limit":10}\'',
     ],
   },
+  'group-management': {
+    summary: 'Manage single-platform tracking groups and memberships.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'name', 'workspaceId or --workspace-id'],
+        optional: [
+          'platform (defaults to tiktok)',
+          'description',
+          'refresh_frequency',
+          'next_refresh_at',
+          'brand_id',
+        ],
+        notes: 'Supported platform values: tiktok, instagram, youtube, ig_reels, yt_shorts, douyin, xhs, google_ai.',
+        example: {
+          action: 'create',
+          name: 'YouTube competitor searches',
+          platform: 'youtube',
+        },
+      },
+      {
+        action: 'add_items',
+        required: ['action=add_items', 'group_id', 'workspaceId or --workspace-id'],
+        optional: ['item_ids', 'items', 'platform/groupPlatform for item payload defaults'],
+        notes: 'When adding item payloads, omit item platform to inherit the group platform, or pass platform explicitly.',
+        example: {
+          action: 'add_items',
+          group_id: 123,
+          items: [
+            {
+              name: 'best kenya safari',
+              type: 'keyword',
+              value: 'best kenya safari',
+              region: 'US',
+            },
+          ],
+        },
+      },
+      {
+        action: 'completeness',
+        required: ['action=completeness', 'group_id', 'items or expected_items', 'workspaceId or --workspace-id'],
+        optional: ['include_refresh_status'],
+        notes: 'Returns durable setup completeness and aggregate refresh queue status for the group.',
+        example: {
+          action: 'completeness',
+          group_id: 123,
+          expected_items: [
+            {
+              track_type: 'search',
+              track_value: 'best kenya safari',
+              region: 'US',
+            },
+          ],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function group-management --workspace-id <workspace-uuid> --body \'{"action":"create","name":"YouTube group","platform":"youtube"}\'',
+      'socialseal tools call --function group-management --workspace-id <workspace-uuid> --body \'{"action":"create","name":"Instagram group","platform":"instagram"}\'',
+      'socialseal tools call --function group-management --workspace-id <workspace-uuid> --body \'{"action":"add_items","group_id":123,"items":[{"name":"best kenya safari","type":"keyword","value":"best kenya safari","region":"US"}]}\'',
+    ],
+  },
 };
 
 function getToolSchemaHint(functionName) {
@@ -1006,6 +1078,11 @@ function isTerminalStatusValue(value) {
   return !ACTIVE_STATUS_VALUES.has(normalized);
 }
 
+function isFailedStatusValue(value) {
+  const normalized = normalizeStatusValue(value);
+  return normalized === 'failed' || normalized === 'error';
+}
+
 function coercePositiveInteger(value, label) {
   if (value === undefined || value === null || value === '') return undefined;
   const parsed = Number(value);
@@ -1104,6 +1181,200 @@ function buildSearchResultsEnrichedExportPayload(rawPayload, workspaceId) {
   });
 }
 
+function buildGoogleAiSearchSummariesExportPayload(rawPayload, workspaceId) {
+  const payload = isJsonObject(rawPayload) ? rawPayload : {};
+  const groupId = coercePositiveInteger(firstDefined(payload, ['groupId', 'group_id']), 'groupId');
+  if (!groupId) {
+    throw new CliError('Google AI evidence export requires a group id.', {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Provide --group-id or groupId in the payload.',
+    });
+  }
+
+  const trackingItemIds = normalizePositiveIntegerList(
+    firstDefined(payload, ['trackingItemIds', 'tracking_item_ids']),
+    'trackingItemIds',
+    { max: 1000 },
+  );
+  const filename = trimString(firstDefined(payload, ['filename'])) || undefined;
+
+  return stripUndefinedEntries({
+    workspaceId,
+    groupId,
+    trackingItemIds: trackingItemIds.length > 0 ? trackingItemIds : undefined,
+    filename,
+  });
+}
+
+function normalizeEvidenceSurface(value) {
+  const normalized = trimString(value || 'auto').toLowerCase().replace(/-/g, '_').replace(/\s+/g, '_');
+  if (['auto', 'social', 'ranked', 'ranked_search', 'google_ai', 'google'].includes(normalized)) {
+    if (normalized === 'ranked' || normalized === 'ranked_search') return 'social';
+    if (normalized === 'google') return 'google_ai';
+    return normalized;
+  }
+  throw new CliError(`Unsupported evidence surface: ${value}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use --surface auto|social|google_ai.',
+  });
+}
+
+function normalizePlatformKey(value) {
+  const normalized = trimString(value).toLowerCase().replace(/-/g, '_').replace(/\s+/g, '_');
+  if (!normalized) return null;
+  if (['google', 'google_ai', 'google_ai_overview', 'ai_search'].includes(normalized)) return 'google_ai';
+  return normalized;
+}
+
+function resolveEvidenceSurfaceFromGroup(group) {
+  if (!isJsonObject(group)) return 'social';
+  const platformId = firstDefined(group, ['platform_id', 'platformId']);
+  if (Number(platformId) === PLATFORM_ID_GOOGLE_AI) return 'google_ai';
+  const platform = normalizePlatformKey(firstDefined(group, ['platform', 'platform_key', 'platformKey']));
+  return platform === 'google_ai' ? 'google_ai' : 'social';
+}
+
+function buildGroupEvidenceMetadata({ surface, groupId, workspaceId, responseJson }) {
+  const metadata = isJsonObject(responseJson) && isJsonObject(responseJson.metadata)
+    ? responseJson.metadata
+    : {};
+  const rowCount = Number.isFinite(metadata.row_count) ? metadata.row_count : null;
+  return {
+    group_id: groupId,
+    workspace_id: workspaceId,
+    platform: surface === 'google_ai' ? 'google_ai' : 'social',
+    surface,
+    row_count: rowCount,
+    generated_at: new Date().toISOString(),
+    header_only: rowCount === 0,
+    template: metadata.template ?? (surface === 'google_ai'
+      ? EXPORT_DATA_TEMPLATE_GOOGLE_AI_SEARCH_SUMMARIES_RAW
+      : EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW),
+  };
+}
+
+function normalizeCompletenessPlatform(rawItem) {
+  const platformId = firstDefined(rawItem, ['platform_id', 'platformId']);
+  if (Number.isFinite(Number(platformId))) return `id:${Number(platformId)}`;
+  const platform = normalizePlatformKey(firstDefined(rawItem, ['platform', 'platform_key', 'platformKey']));
+  return platform ? `key:${platform}` : '';
+}
+
+function normalizeCompletenessItem(rawItem, index, source) {
+  if (!isJsonObject(rawItem)) {
+    throw new CliError(`Invalid ${source} item at index ${index}: expected an object.`, {
+      code: 'INVALID_MANIFEST',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+
+  const id = coercePositiveInteger(firstDefined(rawItem, ['item_id', 'itemId', 'id']), `${source}[${index}].item_id`);
+  const rawValue = firstDefined(rawItem, ['track_value', 'trackValue', 'value', 'name']);
+  const value = trimString(rawValue).toLowerCase();
+  const rawType = firstDefined(rawItem, ['track_type', 'trackType', 'type']);
+  const type = normalizeTrackingType(rawType) || trimString(rawType).toLowerCase() || '';
+  const region = trimString(firstDefined(rawItem, ['region'])).toUpperCase();
+  const platform = normalizeCompletenessPlatform(rawItem);
+  const hasSemanticKey = Boolean(value && type);
+  const key = hasSemanticKey ? `${type}|${value}|${region}|${platform}` : `id:${id}`;
+  const looseKey = hasSemanticKey ? `${type}|${value}|${region}` : `id:${id}`;
+
+  if (!id && (!value || !type)) {
+    throw new CliError(`Invalid ${source} item at index ${index}: expected item_id or track_type + track_value.`, {
+      code: 'INVALID_MANIFEST',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+
+  return {
+    key,
+    looseKey,
+    item_id: id ?? null,
+    track_type: type || null,
+    track_value: value || null,
+    region: region || null,
+    platform: platform || null,
+    raw: rawItem,
+  };
+}
+
+function extractExpectedManifestItems(manifest) {
+  if (Array.isArray(manifest)) return manifest;
+  if (!isJsonObject(manifest)) {
+    throw new CliError('Invalid completeness manifest: expected an array or object with items.', {
+      code: 'INVALID_MANIFEST',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  const items = firstDefined(manifest, ['items', 'expectedItems', 'expected_items']);
+  if (!Array.isArray(items)) {
+    throw new CliError('Invalid completeness manifest: expected items, expectedItems, or expected_items array.', {
+      code: 'INVALID_MANIFEST',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  return items;
+}
+
+function normalizeActualGroupItem(rawItem, index) {
+  const tracking = isJsonObject(rawItem?.user_tracking) ? rawItem.user_tracking : rawItem;
+  return normalizeCompletenessItem(tracking, index, 'actual_items');
+}
+
+function buildCompletenessDiff({ expectedItems, actualItems, groupId, workspaceId }) {
+  const expected = expectedItems.map((item, index) =>
+    normalizeCompletenessItem(item, index, 'expected_items')
+  );
+  const actual = actualItems.map((item, index) => normalizeActualGroupItem(item, index));
+  const actualByKey = new Map(actual.map((item) => [item.key, item]));
+  const expectedByKey = new Map(expected.map((item) => [item.key, item]));
+  const actualByLooseKey = new Map(actual.map((item) => [item.looseKey, item]));
+  const expectedByLooseKey = new Map(expected.map((item) => [item.looseKey, item]));
+
+  const missing = [];
+  const platformMismatches = [];
+  for (const expectedItem of expected) {
+    if (actualByKey.has(expectedItem.key)) continue;
+    const looseMatch = actualByLooseKey.get(expectedItem.looseKey);
+    if (looseMatch && expectedItem.platform !== looseMatch.platform) {
+      platformMismatches.push({
+        expected: expectedItem.raw,
+        actual: looseMatch.raw,
+        expected_platform: expectedItem.platform,
+        actual_platform: looseMatch.platform,
+      });
+      continue;
+    }
+    missing.push(expectedItem.raw);
+  }
+
+  const extra = [];
+  for (const actualItem of actual) {
+    if (expectedByKey.has(actualItem.key)) continue;
+    const looseMatch = expectedByLooseKey.get(actualItem.looseKey);
+    if (looseMatch && looseMatch.platform !== actualItem.platform) continue;
+    extra.push(actualItem.raw);
+  }
+
+  const complete = missing.length === 0 && extra.length === 0 && platformMismatches.length === 0;
+  return {
+    success: complete,
+    complete,
+    group_id: groupId,
+    workspace_id: workspaceId,
+    expected_count: expected.length,
+    actual_count: actual.length,
+    missing_count: missing.length,
+    extra_count: extra.length,
+    platform_mismatch_count: platformMismatches.length,
+    missing,
+    extra,
+    platform_mismatches: platformMismatches,
+  };
+}
+
 function buildPathWithQuery(basePath, query) {
   const params = new URLSearchParams();
   for (const [key, rawValue] of Object.entries(query || {})) {
@@ -1174,8 +1445,10 @@ function normalizeGroupManagementPayload(payload, fallbackWorkspaceId) {
   const itemId = firstDefined(payload, ['item_id', 'itemId']);
   const itemIds = firstDefined(payload, ['item_ids', 'itemIds']);
   const items = firstDefined(payload, ['items']);
+  const expectedItems = firstDefined(payload, ['expected_items', 'expectedItems']);
   const limit = firstDefined(payload, ['limit']);
   const page = firstDefined(payload, ['page']);
+  const force = firstDefined(payload, ['force']);
   return stripUndefinedEntries({
     action: trimString(firstDefined(payload, ['action'])) || undefined,
     workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
@@ -1194,6 +1467,7 @@ function normalizeGroupManagementPayload(payload, fallbackWorkspaceId) {
       })
       : undefined,
     items: Array.isArray(items) ? items : undefined,
+    expected_items: Array.isArray(expectedItems) ? expectedItems : undefined,
     name: trimString(firstDefined(payload, ['name'])) || undefined,
     description: firstDefined(payload, ['description']),
     platform: trimString(firstDefined(payload, ['platform', 'groupPlatform'])) || undefined,
@@ -1207,6 +1481,7 @@ function normalizeGroupManagementPayload(payload, fallbackWorkspaceId) {
       : firstDefined(payload, ['region']),
     limit: limit !== undefined ? Number(limit) : undefined,
     page: page !== undefined ? Number(page) : undefined,
+    force: force === true || trimString(force).toLowerCase() === 'true' ? true : undefined,
   });
 }
 
@@ -1696,6 +1971,28 @@ function translateGroupManagementAction(payload, workspaceId, originalMethod) {
     };
   }
 
+  if (action === 'completeness' || action === 'group_completeness') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group completeness.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    const expectedItems = Array.isArray(payload.expected_items)
+      ? payload.expected_items
+      : (Array.isArray(payload.items) ? payload.items : undefined);
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/completeness`, { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        expected_items: expectedItems,
+        include_refresh_status: firstDefined(payload, ['include_refresh_status', 'includeRefreshStatus']),
+      }),
+      workspaceId,
+    };
+  }
+
   if (action === 'remove_item' || action === 'group_remove_item') {
     const groupId = coercePositiveInteger(payload.group_id, 'group_id');
     const itemId = coercePositiveInteger(payload.item_id, 'item_id');
@@ -1716,7 +2013,7 @@ function translateGroupManagementAction(payload, workspaceId, originalMethod) {
   throw new CliError(`Unsupported group-management action: ${payload.action}`, {
     code: 'INVALID_ARGUMENT',
     exitCode: EXIT_CODES.USAGE,
-    hint: 'Supported group-management actions: list, get, create, update, delete, refresh, list_items, add_item, add_items, remove_item.',
+    hint: 'Supported group-management actions: list, get, create, update, delete, refresh, list_items, add_item, add_items, completeness, remove_item.',
   });
 }
 
@@ -2005,6 +2302,145 @@ function emitJsonOutput(value, pretty) {
   process.stdout.write(formatJsonOutput(value, pretty) + '\n');
 }
 
+function isGroupManagementBulkAddInvocation(functionName, translated) {
+  if (functionName !== 'group-management') return false;
+  const action = isJsonObject(translated.normalizedPayload)
+    ? trimString(translated.normalizedPayload.action).toLowerCase()
+    : '';
+  return action === 'add_items' || action === 'group_add_items';
+}
+
+function getBulkAddExpectedCount(translated) {
+  return Array.isArray(translated.body) ? translated.body.length : null;
+}
+
+function maybeThrowGroupManagementBulkAddPartialFailure(data, translated) {
+  if (!isJsonObject(data)) return;
+
+  const errors = Array.isArray(data.errors) ? data.errors : [];
+  const expected = getBulkAddExpectedCount(translated);
+  const processed = Number.isFinite(data.items_processed) ? data.items_processed : null;
+  const added = Number.isFinite(data.items_added) ? data.items_added : 0;
+  const linked = Number.isFinite(data.items_linked) ? data.items_linked : 0;
+  const alreadyLinked = Number.isFinite(data.items_already_linked) ? data.items_already_linked : 0;
+  const successful = added + linked + alreadyLinked;
+  const failed = errors.length;
+  const hasErrors = failed > 0;
+  const hasProcessedMismatch = expected !== null && processed !== null && processed !== expected;
+  const hasSuccessMismatch = expected !== null && successful !== expected;
+  const hasVerificationFailure = data.verified === false;
+
+  if (!hasErrors && !hasProcessedMismatch && !hasSuccessMismatch && !hasVerificationFailure) return;
+
+  throw new CliError('group-management add_items partially failed.', {
+    code: 'PARTIAL_FAILURE',
+    exitCode: EXIT_CODES.SERVER,
+    hint: 'Inspect errors[] and re-run add_items after fixing failed items; automation should treat this as an unsuccessful setup.',
+    details: truncateDetails({
+      expected,
+      processed,
+      added,
+      linked,
+      alreadyLinked,
+      successful,
+      failed,
+      verified: data.verified,
+      finalGroupItemCount: data.final_group_item_count,
+      expectedFinalGroupItemCount: data.expected_final_group_item_count,
+      errors,
+      response: data,
+    }),
+  });
+}
+
+function getGroupManagementAction(translated) {
+  return isJsonObject(translated.normalizedPayload)
+    ? trimString(translated.normalizedPayload.action).toLowerCase()
+    : '';
+}
+
+function isGroupManagementRefreshInvocation(functionName, translated) {
+  if (functionName !== 'group-management') return false;
+  const action = getGroupManagementAction(translated);
+  return action === 'refresh' || action === 'group_refresh';
+}
+
+function getGroupManagementGroupId(translated) {
+  return isJsonObject(translated.normalizedPayload)
+    ? coercePositiveInteger(translated.normalizedPayload.group_id, 'group_id')
+    : undefined;
+}
+
+function getGroupItemsCount(data) {
+  if (Array.isArray(data)) return data.length;
+  if (!isJsonObject(data)) return null;
+  if (Number.isFinite(data.total)) return data.total;
+  if (Array.isArray(data.items)) return data.items.length;
+  if (Array.isArray(data.data)) return data.data.length;
+  return null;
+}
+
+async function preflightGroupRefreshNotEmpty({
+  opts,
+  translated,
+  apiBase,
+  apiKey,
+  pathPrefix,
+  workspaceId,
+  timeoutMs,
+}) {
+  if (!isGroupManagementRefreshInvocation(opts.function, translated)) return;
+  if (translated.normalizedPayload?.force === true) return;
+
+  const groupId = getGroupManagementGroupId(translated);
+  if (!groupId) return;
+
+  const res = await callApi({
+    apiBase,
+    apiKey,
+    path: `${pathPrefix}/groups/${groupId}/items?${new URLSearchParams({
+      workspace_id: workspaceId,
+      page: '1',
+      limit: '1',
+    }).toString()}`,
+    method: 'GET',
+    workspaceId,
+    timeoutMs,
+  });
+
+  if (!res.ok) {
+    throw await buildHttpError(res, {
+      label: 'Group refresh preflight',
+      functionName: 'group-management',
+      method: 'GET',
+    });
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (!contentType.includes('application/json')) {
+    throw new CliError('Group refresh preflight returned a non-JSON response.', {
+      code: 'INVALID_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
+  const data = await res.json();
+  const itemCount = getGroupItemsCount(data);
+  if (itemCount === 0) {
+    throw new CliError('Refusing to refresh an empty tracking group.', {
+      code: 'EMPTY_GROUP_REFRESH',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Add items to the group first, or pass force:true in the group-management payload to override.',
+      details: truncateDetails({
+        groupId,
+        workspaceId,
+        itemCount,
+        response: data,
+      }),
+    });
+  }
+}
+
 function buildSearchJourneyRunFailure(data) {
   const message = isJsonObject(data) && typeof data.error === 'string' && data.error.trim().length > 0
     ? data.error
@@ -3188,6 +3624,18 @@ async function handleToolsCall(opts) {
     method,
   });
 
+  if (isGroupManagementRefreshInvocation(opts.function, translated)) {
+    await preflightGroupRefreshNotEmpty({
+      opts,
+      translated,
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      pathPrefix: useGateway ? '/cli/tools/group-management' : '/functions/v1/group-management',
+      workspaceId: effectiveWorkspaceId,
+      timeoutMs,
+    });
+  }
+
   const res = await callApi({
     apiBase: useGateway ? resolvedApiBase : legacyUrl,
     apiKey,
@@ -3211,6 +3659,9 @@ async function handleToolsCall(opts) {
     const data = await res.json();
     const shouldPoll = shouldHandleSearchJourneyRunAsync(opts.function, method, payload, opts) && opts.poll !== false;
     if (!shouldPoll) {
+      if (isGroupManagementBulkAddInvocation(opts.function, translated)) {
+        maybeThrowGroupManagementBulkAddPartialFailure(data, translated);
+      }
       maybeEmitFollowupStatusHint({
         functionName: opts.function,
         data,
@@ -3433,6 +3884,14 @@ async function handleToolsStatus(opts) {
     ...result,
     hint: commandHint,
   };
+  if (opts.wait && isFailedStatusValue(result.status)) {
+    throw new CliError(`${result.kind} reached terminal ${result.status} status.`, {
+      code: 'STATUS_FAILED',
+      exitCode: EXIT_CODES.SERVER,
+      hint: commandHint,
+      details: truncateDetails(payload),
+    });
+  }
   emitJsonOutput(payload, opts.pretty);
 }
 
@@ -3586,46 +4045,27 @@ async function handleDataExportReport(opts) {
   process.stdout.write(JSON.stringify(json, null, opts.pretty ? 2 : 0) + '\n');
 }
 
-async function handleDataExportSearchResults(opts) {
-  const config = loadConfig();
-  const apiKey = requireApiKey(opts, config);
-  const apiBase = resolveApiBase(opts, config);
-  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
-  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
-  const timeoutMs = resolveTimeoutMs(opts, config);
-  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
-
-  const rawPayload = opts.__rawPayload ?? stripUndefinedEntries({
-    groupIds: normalizePositiveIntegerList(opts.groupIds, 'groupIds', { max: 100 }),
-    trackingItemIds: normalizePositiveIntegerList(opts.trackingItemIds, 'trackingItemIds', { max: 1000 }),
-    dateFrom: opts.dateFrom,
-    dateTo: opts.dateTo,
-    filename: opts.filename,
-  });
-
-  const payloadWorkspaceId = resolvePayloadWorkspaceId(rawPayload, null);
-  const effectiveWorkspaceId = requireWorkspaceSelection(payloadWorkspaceId || resolvedWorkspaceId, {
-    label: 'Search results enriched export',
-    hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before exporting.',
-  });
-  const effectiveWorkspaceSource = payloadWorkspaceId ? 'body' : workspaceSource;
-  emitWorkspaceSelectionNotice(opts, {
-    workspaceId: effectiveWorkspaceId,
-    source: effectiveWorkspaceSource,
-    label: 'search_results_enriched export',
-  });
-
-  const normalizedPayload = buildSearchResultsEnrichedExportPayload(rawPayload, effectiveWorkspaceId);
-  const requestedFilename = trimString(normalizedPayload.filename) || undefined;
-  delete normalizedPayload.filename;
-
+async function runExportDataCsv({
+  opts,
+  label,
+  template,
+  normalizedPayload,
+  requestedFilename,
+  effectiveWorkspaceId,
+  apiBase,
+  apiKey,
+  useGateway,
+  legacyUrl,
+  timeoutMs,
+  decorateResponse,
+}) {
   const exportResponse = await callApi({
-    apiBase: useGateway ? resolvedApiBase : legacyUrl,
+    apiBase: useGateway ? apiBase : legacyUrl,
     apiKey,
     path: useGateway ? '/cli/tools/export-data' : '/functions/v1/export-data',
     method: 'POST',
     body: {
-      template: EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW,
+      template,
       format: 'csv',
       payload: normalizedPayload,
       filename: requestedFilename,
@@ -3636,13 +4076,16 @@ async function handleDataExportSearchResults(opts) {
 
   if (!exportResponse.ok) {
     throw await buildHttpError(exportResponse, {
-      label: 'Search results enriched export',
+      label,
       functionName: 'export-data',
       method: 'POST',
     });
   }
 
   const responseJson = await exportResponse.json();
+  const decoratedResponse = typeof decorateResponse === 'function'
+    ? decorateResponse(responseJson)
+    : responseJson;
   const metadata = isJsonObject(responseJson) && isJsonObject(responseJson.metadata)
     ? responseJson.metadata
     : null;
@@ -3657,7 +4100,7 @@ async function handleDataExportSearchResults(opts) {
     } else {
       process.stderr.write('[socialseal] Export did not include a file URL yet. Inspect the JSON metadata and retry if needed.\n');
     }
-    emitJsonOutput(responseJson, opts.pretty);
+    emitJsonOutput(decoratedResponse, opts.pretty);
     return;
   }
 
@@ -3668,7 +4111,7 @@ async function handleDataExportSearchResults(opts) {
 
   if (!artifactResponse.ok) {
     throw await buildHttpError(artifactResponse, {
-      label: 'Search results enriched artifact download',
+      label: `${label} artifact download`,
       method: 'GET',
       hint: 'The signed file URL may be expired or inaccessible. Re-run the export command to mint a fresh URL.',
     });
@@ -3683,7 +4126,7 @@ async function handleDataExportSearchResults(opts) {
 
   const outPath = opts.stdout
     ? null
-    : (opts.out || trimString(metadata?.filename || '') || 'tracking-ranked-videos.csv');
+    : (opts.out || trimString(metadata?.filename || '') || `${template}.csv`);
   if (outPath) {
     await pipeline(artifactResponse.body, fs.createWriteStream(outPath));
     process.stderr.write(`[socialseal] Export written to ${outPath}\n`);
@@ -3692,6 +4135,261 @@ async function handleDataExportSearchResults(opts) {
   }
 }
 
+async function handleDataExportSearchResults(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const rawPayload = opts.__rawPayload ?? stripUndefinedEntries({
+    groupIds: normalizePositiveIntegerList(opts.groupIds, 'groupIds', { max: 100 }),
+    trackingItemIds: normalizePositiveIntegerList(opts.trackingItemIds, 'trackingItemIds', { max: 1000 }),
+    dateFrom: opts.dateFrom,
+    dateTo: opts.dateTo,
+    filename: opts.filename,
+  });
+
+  const payloadWorkspaceId = resolvePayloadWorkspaceId(rawPayload, null);
+  const effectiveWorkspaceId = requireWorkspaceSelection(payloadWorkspaceId || resolvedWorkspaceId, {
+    label: 'Search results enriched export',
+    hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before exporting.',
+  });
+  const effectiveWorkspaceSource = payloadWorkspaceId ? 'body' : workspaceSource;
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
+    label: 'search_results_enriched export',
+  });
+
+  const normalizedPayload = buildSearchResultsEnrichedExportPayload(rawPayload, effectiveWorkspaceId);
+  const requestedFilename = trimString(normalizedPayload.filename) || undefined;
+  delete normalizedPayload.filename;
+
+  await runExportDataCsv({
+    opts,
+    label: 'Search results enriched export',
+    template: EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW,
+    normalizedPayload,
+    requestedFilename,
+    effectiveWorkspaceId,
+    apiBase: resolvedApiBase,
+    apiKey,
+    useGateway,
+    legacyUrl,
+    timeoutMs,
+  });
+}
+
+async function handleDataExportGroupEvidence(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const groupId = coercePositiveInteger(opts.groupId, 'group_id');
+  const effectiveWorkspaceId = requireWorkspaceSelection(resolvedWorkspaceId, {
+    label: 'Group evidence export',
+    hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before exporting group evidence.',
+  });
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: workspaceSource,
+    label: 'group evidence export',
+  });
+
+  const requestedSurface = normalizeEvidenceSurface(opts.surface);
+  let surface = requestedSurface;
+  if (requestedSurface === 'auto') {
+    const groupResponse = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path: useGateway
+        ? `/cli/tools/group-management/groups/${groupId}?workspace_id=${encodeURIComponent(effectiveWorkspaceId)}`
+        : `/functions/v1/group-management/groups/${groupId}?workspace_id=${encodeURIComponent(effectiveWorkspaceId)}`,
+      method: 'GET',
+      workspaceId: effectiveWorkspaceId,
+      timeoutMs,
+    });
+
+    if (!groupResponse.ok) {
+      throw await buildHttpError(groupResponse, {
+        label: 'Group evidence platform detection',
+        functionName: 'group-management',
+        method: 'GET',
+      });
+    }
+
+    const groupData = await groupResponse.json();
+    surface = resolveEvidenceSurfaceFromGroup(groupData);
+  }
+
+  const rawPayload = stripUndefinedEntries({
+    groupId,
+    groupIds: surface === 'social' ? [groupId] : undefined,
+    trackingItemIds: normalizePositiveIntegerList(opts.trackingItemIds, 'trackingItemIds', { max: 1000 }),
+    dateFrom: opts.dateFrom,
+    dateTo: opts.dateTo,
+    filename: opts.filename,
+  });
+  const normalizedPayload = surface === 'google_ai'
+    ? buildGoogleAiSearchSummariesExportPayload(rawPayload, effectiveWorkspaceId)
+    : buildSearchResultsEnrichedExportPayload(rawPayload, effectiveWorkspaceId);
+  const requestedFilename = trimString(normalizedPayload.filename) || undefined;
+  delete normalizedPayload.filename;
+  const template = surface === 'google_ai'
+    ? EXPORT_DATA_TEMPLATE_GOOGLE_AI_SEARCH_SUMMARIES_RAW
+    : EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW;
+
+  await runExportDataCsv({
+    opts,
+    label: 'Group evidence export',
+    template,
+    normalizedPayload,
+    requestedFilename,
+    effectiveWorkspaceId,
+    apiBase: resolvedApiBase,
+    apiKey,
+    useGateway,
+    legacyUrl,
+    timeoutMs,
+    decorateResponse: (responseJson) => ({
+      ...responseJson,
+      evidence: buildGroupEvidenceMetadata({
+        surface,
+        groupId,
+        workspaceId: effectiveWorkspaceId,
+        responseJson,
+      }),
+    }),
+  });
+}
+
+async function handleDataGroupCompleteness(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const groupId = coercePositiveInteger(opts.groupId, 'group_id');
+  const effectiveWorkspaceId = requireWorkspaceSelection(resolvedWorkspaceId, {
+    label: 'Group completeness check',
+    hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before checking group completeness.',
+  });
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: workspaceSource,
+    label: 'group completeness check',
+  });
+
+  const manifest = parseJsonInput(opts.manifest, { label: 'manifest' });
+  const expectedItems = extractExpectedManifestItems(manifest);
+  const backendPath = useGateway
+    ? `/cli/tools/group-management/groups/${groupId}/completeness?${new URLSearchParams({
+      workspace_id: effectiveWorkspaceId,
+    }).toString()}`
+    : `/functions/v1/group-management/groups/${groupId}/completeness?${new URLSearchParams({
+      workspace_id: effectiveWorkspaceId,
+    }).toString()}`;
+
+  const backendRes = await callApi({
+    apiBase: useGateway ? resolvedApiBase : legacyUrl,
+    apiKey,
+    path: backendPath,
+    method: 'POST',
+    body: {
+      expected_items: expectedItems,
+      include_refresh_status: true,
+    },
+    workspaceId: effectiveWorkspaceId,
+    timeoutMs,
+  });
+
+  if (backendRes.ok) {
+    const contentType = backendRes.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('Group completeness check returned a non-JSON response.', {
+        code: 'INVALID_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+    const backendData = await backendRes.json();
+    emitJsonOutput(backendData, opts.pretty);
+    if (isJsonObject(backendData) && backendData.complete === false) {
+      process.exitCode = EXIT_CODES.SERVER;
+    }
+    return;
+  }
+
+  if (backendRes.status !== 404) {
+    throw await buildHttpError(backendRes, {
+      label: 'Group completeness check',
+      functionName: 'group-management',
+      method: 'POST',
+    });
+  }
+
+  const res = await callApi({
+    apiBase: useGateway ? resolvedApiBase : legacyUrl,
+    apiKey,
+    path: useGateway
+      ? `/cli/tools/group-management/groups/${groupId}/items?${new URLSearchParams({
+        workspace_id: effectiveWorkspaceId,
+        page: '1',
+        limit: String(Math.max(expectedItems.length + 100, 1000)),
+      }).toString()}`
+      : `/functions/v1/group-management/groups/${groupId}/items?${new URLSearchParams({
+        workspace_id: effectiveWorkspaceId,
+        page: '1',
+        limit: String(Math.max(expectedItems.length + 100, 1000)),
+      }).toString()}`,
+    method: 'GET',
+    workspaceId: effectiveWorkspaceId,
+    timeoutMs,
+  });
+
+  if (!res.ok) {
+    throw await buildHttpError(res, {
+      label: 'Group completeness check',
+      functionName: 'group-management',
+      method: 'GET',
+    });
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (!contentType.includes('application/json')) {
+    throw new CliError('Group completeness check returned a non-JSON response.', {
+      code: 'INVALID_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
+  const data = await res.json();
+  const actualItems = isJsonObject(data) && Array.isArray(data.items)
+    ? data.items
+    : (Array.isArray(data) ? data : []);
+  const diff = buildCompletenessDiff({
+    expectedItems,
+    actualItems,
+    groupId,
+    workspaceId: effectiveWorkspaceId,
+  });
+  diff.source = 'manifest_fallback';
+
+  emitJsonOutput(diff, opts.pretty);
+  if (!diff.complete) {
+    process.exitCode = EXIT_CODES.SERVER;
+  }
+}
+
 function handleDataExportOptions(opts) {
   const payload = {
     exports: EXPORT_OPTIONS,
@@ -4053,7 +4751,7 @@ if (typeof program.showHelpAfterError === 'function') {
 if (typeof program.showSuggestionAfterError === 'function') {
   program.showSuggestionAfterError(true);
 }
-program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message "ping"\n  socialseal tools list\n  socialseal tools schema --function search-journey-run\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools status 6809 --kind google_ai_run\n  socialseal tools status <run-uuid> --kind journey_run --workspace-id <uuid>\n  socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>\n  socialseal video extract --video-id 734829384 --wait --out-dir ./video-assets\n  socialseal data export-options\n  socialseal data export-tracking --group-id 123 --time-period 30d\n  socialseal data export-search-results --group-ids 123,124 --workspace-id <uuid> --out ranked.csv\n`);
+program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message "ping"\n  socialseal tools list\n  socialseal tools schema --function search-journey-run\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools status 6809 --kind google_ai_run\n  socialseal tools status <run-uuid> --kind journey_run --workspace-id <uuid>\n  socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>\n  socialseal video extract --video-id 734829384 --wait --out-dir ./video-assets\n  socialseal data export-options\n  socialseal data export-tracking --group-id 123 --time-period 30d\n  socialseal data export-search-results --group-ids 123,124 --workspace-id <uuid> --out ranked.csv\n  socialseal data export-group-evidence --group-id 123 --workspace-id <uuid> --out evidence.csv\n`);
 
 program
   .command('agent')
@@ -4214,6 +4912,40 @@ data
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleDataExportSearchResults, opts));
 
+data
+  .command('export-group-evidence')
+  .description('Export usable group evidence, routing social groups and Google AI groups to the correct CSV export')
+  .requiredOption('--group-id <id>', 'Tracking group id')
+  .option('--surface <surface>', 'auto|social|google_ai', 'auto')
+  .option('--tracking-item-ids <ids>', 'Optional comma-separated tracking item ids')
+  .option('--date-from <iso>', 'Optional ISO datetime lower bound for social ranked exports')
+  .option('--date-to <iso>', 'Optional ISO datetime upper bound for social ranked exports')
+  .option('--filename <name>', 'Optional export filename stem (without extension)')
+  .option('--out <path>', 'Output file path')
+  .option('--stdout', 'Write to stdout')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--pretty', 'Pretty-print JSON metadata when no file is ready')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleDataExportGroupEvidence, opts));
+
+data
+  .command('group-completeness')
+  .description('Compare an expected tracking-item manifest against current group items')
+  .requiredOption('--group-id <id>', 'Tracking group id')
+  .requiredOption('--manifest <jsonOrFile>', 'Expected items manifest JSON or @file.json')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleDataGroupCompleteness, opts));
+
 data
   .command('export-report')
   .description('Export report data via export-report (provisional)')