@socialseal/cli 0.1.6 → 0.1.8

package/src/index.js

@@ -10,14 +10,16 @@ const DEFAULT_CONFIG_PATH = path.join(os.homedir(), '.config', 'socialseal', 'co
 const DEFAULT_API_BASE = 'https://api.socialseal.co';
 const CLI_KEY_HEADER = 'X-CLI-Key';
 const WORKSPACE_HEADER = 'X-Workspace-Id';
-const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_TIMEOUT_MS = 300000;
 const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 300000;
 const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_STATUS_RESULTS_LIMIT = 10;
 const DEFAULT_FRAME_COUNT = 3;
 const MAX_TIMEOUT_MS = 900000;
 const LEGACY_ENABLED = process.env.SOCIALSEAL_ENABLE_LEGACY === '1';
 const CLI_VERSION = loadRuntimeVersion();
 const STATIC_TOOL_REGISTRY_NOTE = 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration, so environment-specific availability can drift.';
+const STATIC_TOOL_SCHEMA_NOTE = 'Schema hints are static CLI docs for discoverability. Backend contracts can still evolve.';
 const EXIT_CODES = {
   OK: 0,
   UNKNOWN: 1,
@@ -27,8 +29,58 @@ const EXIT_CODES = {
   SERVER: 5,
 };
 const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+const ACTIVE_STATUS_VALUES = new Set(['queued', 'pending', 'processing', 'in_progress', 'running']);
+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 SUPPORTED_EXPORT_REPORT_TYPES = [
+  'keyword_universe',
+  'cluster_insights',
+  'creator_signatures',
+  'post_publish',
+  'quick_audit',
+  REPORT_TYPE_SEARCH_RESULTS_ENRICHED,
+];
+const EXPORT_OPTIONS = [
+  {
+    id: 'tracking_csv',
+    command: 'socialseal data export-tracking --group-id <id> --time-period <window>',
+    summary: 'Legacy tracking CSV export for a group or tracking item.',
+    formats: ['csv'],
+    required: ['workspace id', '--group-id or --item-id', '--time-period'],
+    bestFor: 'Quick tracking-table exports and backwards-compatible pipelines.',
+  },
+  {
+    id: 'search_results_enriched',
+    command: 'socialseal data export-search-results --group-ids <id,id,...>',
+    summary: 'Enriched ranked search rows (search results + video + latest metrics + analysis).',
+    formats: ['csv'],
+    required: ['workspace id', '--group-ids'],
+    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: 'report_templates',
+    command: 'socialseal data export-report --report-type <type> --format <format> --payload @payload.json',
+    summary: 'Report-template exports via export-report.',
+    formats: ['csv', 'json', 'markdown', 'html', 'excel_data'],
+    required: ['payload JSON'],
+    bestFor: 'Keyword universe, clusters, creators, post-publish timeline, and quick-audit exports.',
+    reportTypes: SUPPORTED_EXPORT_REPORT_TYPES,
+  },
+];
 const KNOWN_TOOLS = [
-  { name: 'agent-tool-jobs', category: 'agent', description: 'Poll queued agent-backed tool jobs and fetch their results.' },
+  {
+    name: 'agent-tool-jobs',
+    category: 'agent',
+    description: 'Queue/poll agent-backed tool jobs.',
+    objectType: 'agent_tool_job',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['start', 'status'],
+    notes: 'Use action=start to queue and action=status to read a UUID job id.',
+  },
   { name: 'deep-exploration-runs', category: 'agent', description: 'Read or persist deep exploration render runs.' },
   { name: 'workspace-notes', category: 'agent', description: 'Search, create, update, and pin workspace note memory.' },
   { name: 'workspace-onboarding', category: 'agent', description: 'Read or update workspace onboarding metadata used by the agent.' },
@@ -54,6 +106,16 @@ const KNOWN_TOOLS = [
     notes: 'Refreshes brand metrics for brands/workspaces. It does not refresh a tracking group by UUID.',
   },
   { name: 'export-report', category: 'export', description: 'Generate report exports (csv/json/markdown/html/excel_data).' },
+  {
+    name: 'export-data',
+    category: 'export',
+    description: 'Run raw workspace-scoped export templates with signed-URL artifacts.',
+    objectType: 'workspace_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'disabled_by_default',
+    notes: 'Includes template `tracking_ranked_videos_raw` for ranked search results with video + metrics + analysis enrichment.',
+  },
   {
     name: 'export_tracking_data',
     category: 'export',
@@ -75,7 +137,36 @@ const KNOWN_TOOLS = [
     notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items; videoId means video_uid or platform-native video id, not a tracking item id.',
   },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
-  { name: 'google-ai-search', category: 'search', description: 'Run Google AI search queries and fetch result snapshots.' },
+  {
+    name: 'google-ai-search',
+    category: 'search',
+    description: 'Queue Google AI search runs.',
+    objectType: 'google_ai_run',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Returns numeric runId. Read status/results via get-google-ai-search-runs/get-google-ai-search-results or socialseal tools status <runId>.',
+  },
+  {
+    name: 'get-google-ai-search-runs',
+    category: 'search',
+    description: 'Read Google AI run queue/progress by numeric run id.',
+    objectType: 'google_ai_run',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Primary status endpoint for numeric Google AI run ids.',
+  },
+  {
+    name: 'get-google-ai-search-results',
+    category: 'search',
+    description: 'Read Google AI summaries/citations by numeric run id.',
+    objectType: 'google_ai_summary',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Use this after a run reaches succeeded/partial/failed to inspect summary-level output.',
+  },
   { name: 'instagram-geo-api', category: 'search', description: 'Query Instagram search and geo data.' },
   { name: 'tiktok-geo-api', category: 'search', description: 'Query TikTok search and geo data.' },
   { name: 'xhs-geo-api', category: 'search', description: 'Query Xiaohongshu search and geo data.' },
@@ -104,7 +195,16 @@ const KNOWN_TOOLS = [
   },
   { name: 'journey-feedback', category: 'vnext', description: 'Record acceptance or rejection feedback for opportunity bundles.' },
   { name: 'opportunity-bundle-approve', category: 'vnext', description: 'Approve an opportunity bundle and create tracking coverage.' },
-  { name: 'search-journey-run', category: 'vnext', description: 'Run a search journey for a subject across supported platforms.' },
+  {
+    name: 'search-journey-run',
+    category: 'vnext',
+    description: 'Run or poll a search journey for a subject across supported platforms.',
+    objectType: 'search_journey_run',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Async start returns runId; poll with action=status or socialseal tools status <runId> --kind journey_run --workspace-id <workspace-id>.',
+  },
   { 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.' },
@@ -120,6 +220,183 @@ const KNOWN_TOOLS = [
   { name: 'vnext-topics-auto-tag', category: 'vnext', description: 'Auto-tag keyword and topic assignments with Gemini-assisted review.' },
 ];
 
+const TOOL_SCHEMA_HINTS = {
+  'agent-tool-jobs': {
+    summary: 'Queue agent-backed jobs and read UUID job status.',
+    operations: [
+      {
+        action: 'start',
+        required: ['action=start', 'toolName', 'payload'],
+        optional: [],
+        example: {
+          action: 'start',
+          toolName: 'search_videos',
+          payload: {
+            query: 'best africa safari itinerary',
+            platform: 'tiktok',
+            region: 'IN',
+            limit: 20,
+          },
+        },
+      },
+      {
+        action: 'status',
+        required: ['action=status', 'jobId (uuid)'],
+        optional: [],
+        example: {
+          action: 'status',
+          jobId: '11111111-1111-4111-8111-111111111111',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function agent-tool-jobs --body \'{"action":"start","toolName":"search_videos","payload":{"query":"best africa safari itinerary","platform":"tiktok","region":"IN"}}\'',
+      'socialseal tools status 11111111-1111-4111-8111-111111111111 --kind agent_job',
+    ],
+  },
+  'search-journey-run': {
+    summary: 'Start/poll journey keyword expansion runs.',
+    operations: [
+      {
+        action: 'start',
+        required: ['subject', 'subjectType', 'region', 'workspaceId'],
+        optional: [
+          'locale',
+          'platformKeys',
+          'seedKeywords',
+          'contentPillars',
+          'contentPillarIds',
+          'maxKeywords',
+          'maxKeywordsPerStage',
+          'includeRejected',
+          'skipCache',
+          'executionMode',
+        ],
+        example: {
+          subject: 'Como Hotels',
+          subjectType: 'brand',
+          region: 'IN',
+          locale: 'en-IN',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          executionMode: 'async',
+        },
+      },
+      {
+        action: 'status',
+        required: ['action=status', 'workspaceId', 'runId (uuid)'],
+        optional: [],
+        example: {
+          action: 'status',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          runId: '11111111-1111-4111-8111-111111111111',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function search-journey-run --body @journey.json --async --workspace-id <workspace-uuid>',
+      'socialseal tools status 11111111-1111-4111-8111-111111111111 --kind journey_run --workspace-id <workspace-uuid>',
+    ],
+  },
+  'google-ai-search': {
+    summary: 'Queue Google AI runs (returns numeric runId).',
+    operations: [
+      {
+        action: 'start',
+        required: ['queries'],
+        optional: [
+          'workspaceId',
+          'trackingItemId',
+          'countryCode',
+          'searchLanguage',
+          'brandId',
+          'competitorBrandIds',
+          'brandDomains',
+          'competitorDomains',
+          'aiMode',
+        ],
+        notes: 'region is commonly used in workflows, but the canonical field is countryCode.',
+        example: {
+          queries: ['east africa itinerary', 'kenya tanzania itinerary'],
+          countryCode: 'in',
+          searchLanguage: 'en',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function google-ai-search --body @google-ai-search.json --workspace-id <workspace-uuid>',
+      'socialseal tools status 6809 --kind google_ai_run',
+    ],
+  },
+  'get-google-ai-search-runs': {
+    summary: 'Read Google AI run status/progress.',
+    operations: [
+      {
+        action: 'read',
+        required: [],
+        optional: ['runId', 'trackingItemId', 'limit', 'offset', 'skipCache'],
+        example: {
+          runId: 6809,
+          limit: 1,
+          offset: 0,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function get-google-ai-search-runs --body \'{"runId":6809,"limit":1}\'',
+      'socialseal tools status 6809 --kind google_ai_run',
+    ],
+  },
+  'get-google-ai-search-results': {
+    summary: 'Read Google AI summary/citation rows.',
+    operations: [
+      {
+        action: 'read',
+        required: [],
+        optional: ['runId', 'query', 'trackingItemId', 'includeCitations', 'limit', 'offset', 'skipCache'],
+        example: {
+          runId: 6809,
+          includeCitations: true,
+          limit: 10,
+          offset: 0,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function get-google-ai-search-results --body \'{"runId":6809,"includeCitations":true,"limit":10}\'',
+    ],
+  },
+};
+
+function getToolSchemaHint(functionName) {
+  if (!functionName) return null;
+  return TOOL_SCHEMA_HINTS[functionName] || null;
+}
+
+function getKnownTool(functionName) {
+  return KNOWN_TOOLS.find((tool) => tool.name === functionName) || null;
+}
+
+function buildSchemaAvailabilitySummary(schema) {
+  const firstOperation = Array.isArray(schema?.operations) ? schema.operations[0] : null;
+  if (!firstOperation || !Array.isArray(firstOperation.required) || firstOperation.required.length === 0) {
+    return 'optional body fields vary by read filter';
+  }
+  return `required: ${firstOperation.required.join(', ')}`;
+}
+
+function buildToolRegistry() {
+  return KNOWN_TOOLS.map((tool) => {
+    const schema = getToolSchemaHint(tool.name);
+    if (!schema) return tool;
+    return {
+      ...tool,
+      schemaAvailable: true,
+      schemaSummary: buildSchemaAvailabilitySummary(schema),
+    };
+  });
+}
+
 function getConfigPath() {
   return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
 }
@@ -675,6 +952,60 @@ function isUuidLike(value) {
   return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.trim());
 }
 
+function isPositiveIntegerString(value) {
+  return typeof value === 'string' && /^[1-9]\d*$/.test(value.trim());
+}
+
+function normalizeStatusIdentifier(rawId) {
+  const id = trimString(rawId);
+  if (!id) {
+    throw new CliError('Missing status identifier.', {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass a numeric Google AI runId or a UUID job/run id.',
+    });
+  }
+
+  if (isPositiveIntegerString(id)) {
+    const parsed = Number(id);
+    if (Number.isSafeInteger(parsed) && parsed > 0) {
+      return { rawId: id, numericId: parsed, uuidId: null };
+    }
+  }
+
+  if (isUuidLike(id)) {
+    return { rawId: id, numericId: null, uuidId: id };
+  }
+
+  throw new CliError(`Unsupported status identifier: ${id}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use a numeric Google AI runId (for example 6809) or UUID job/run id.',
+  });
+}
+
+function parseToolStatusKind(rawKind) {
+  const normalized = trimString(rawKind || 'auto').toLowerCase();
+  if (TOOL_STATUS_KINDS.has(normalized)) {
+    return normalized;
+  }
+  throw new CliError(`Unsupported tools status kind: ${rawKind}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use --kind auto|agent_job|google_ai_run|journey_run.',
+  });
+}
+
+function normalizeStatusValue(value) {
+  return trimString(value).toLowerCase();
+}
+
+function isTerminalStatusValue(value) {
+  const normalized = normalizeStatusValue(value);
+  if (!normalized) return true;
+  return !ACTIVE_STATUS_VALUES.has(normalized);
+}
+
 function coercePositiveInteger(value, label) {
   if (value === undefined || value === null || value === '') return undefined;
   const parsed = Number(value);
@@ -691,6 +1022,88 @@ function coercePositiveInteger(value, label) {
   });
 }
 
+function normalizePositiveIntegerList(value, label, { max } = {}) {
+  if (value === undefined || value === null || value === '') return [];
+  const entries = Array.isArray(value)
+    ? value
+    : String(value)
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  const parsed = entries.map((entry, index) => {
+    const normalized = coercePositiveInteger(entry, `${label}[${index}]`);
+    if (!normalized) {
+      throw new CliError(`Invalid ${label}[${index}] value.`, {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return normalized;
+  });
+  const deduped = Array.from(new Set(parsed));
+  if (max && deduped.length > max) {
+    throw new CliError(`Too many ${label} values: received ${deduped.length}, max is ${max}.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  return deduped;
+}
+
+function normalizeIsoDateTime(value, label) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string') {
+    throw new CliError(`Invalid ${label}: expected an ISO datetime string.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  const trimmed = value.trim();
+  const epoch = Date.parse(trimmed);
+  if (Number.isNaN(epoch)) {
+    throw new CliError(`Invalid ${label}: expected an ISO datetime string.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      details: value,
+    });
+  }
+  return new Date(epoch).toISOString();
+}
+
+function buildSearchResultsEnrichedExportPayload(rawPayload, workspaceId) {
+  const payload = isJsonObject(rawPayload) ? rawPayload : {};
+  const groupIds = normalizePositiveIntegerList(
+    firstDefined(payload, ['groupIds', 'group_ids']),
+    'groupIds',
+    { max: 100 },
+  );
+  if (groupIds.length === 0) {
+    throw new CliError('search_results_enriched export requires at least one group id.', {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Provide --group-ids for `data export-search-results`, or include groupIds in --payload for `data export-report`.',
+    });
+  }
+
+  const trackingItemIds = normalizePositiveIntegerList(
+    firstDefined(payload, ['trackingItemIds', 'tracking_item_ids']),
+    'trackingItemIds',
+    { max: 1000 },
+  );
+  const dateFrom = normalizeIsoDateTime(firstDefined(payload, ['dateFrom', 'date_from']), 'dateFrom');
+  const dateTo = normalizeIsoDateTime(firstDefined(payload, ['dateTo', 'date_to']), 'dateTo');
+  const filename = trimString(firstDefined(payload, ['filename'])) || undefined;
+
+  return stripUndefinedEntries({
+    workspaceId,
+    groupIds,
+    trackingItemIds: trackingItemIds.length > 0 ? trackingItemIds : undefined,
+    dateFrom,
+    dateTo,
+    filename,
+  });
+}
+
 function buildPathWithQuery(basePath, query) {
   const params = new URLSearchParams();
   for (const [key, rawValue] of Object.entries(query || {})) {
@@ -1669,14 +2082,17 @@ async function pollSearchJourneyRun({
 
     const data = await res.json();
     const status = isJsonObject(data) && typeof data.status === 'string' ? data.status : null;
+    const normalizedStatus = normalizeStatusValue(status);
     if (status && status !== lastStatus) {
       emitInfo(opts, `search-journey-run status: ${status}`);
       lastStatus = status;
     }
 
-    if (status === 'completed') return data;
-    if (status === 'failed') throw buildSearchJourneyRunFailure(data);
-    if (status === 'pending' || status === 'processing') continue;
+    if (normalizedStatus === 'completed' || normalizedStatus === 'succeeded') return data;
+    if (normalizedStatus === 'failed' || normalizedStatus === 'error') {
+      throw buildSearchJourneyRunFailure(data);
+    }
+    if (normalizedStatus && ACTIVE_STATUS_VALUES.has(normalizedStatus)) continue;
 
     throw new CliError('search-journey-run status poll returned an unexpected payload.', {
       code: 'INVALID_STATUS_RESPONSE',
@@ -1695,7 +2111,9 @@ function mapStatusToExitCode(status) {
 }
 
 function isLocallyDisabledByDefaultFunction(functionName) {
-  return functionName === 'group-management' || functionName === 'export_tracking_data';
+  return functionName === 'group-management'
+    || functionName === 'export_tracking_data'
+    || functionName === 'export-data';
 }
 
 function buildStatusHint(status, context = {}) {
@@ -1753,6 +2171,428 @@ async function buildHttpError(res, context = {}) {
   });
 }
 
+function resolveStatusResultsLimit(rawLimit) {
+  if (rawLimit == null || rawLimit === '') return DEFAULT_STATUS_RESULTS_LIMIT;
+  const parsed = Number(rawLimit);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new CliError('Invalid results limit. Use a positive integer.', {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use --results-limit <n> where n is between 1 and 50.',
+    });
+  }
+  return Math.min(parsed, 50);
+}
+
+async function callToolJson({
+  apiBase,
+  apiKey,
+  useGateway,
+  legacyUrl,
+  functionName,
+  body,
+  workspaceId,
+  timeoutMs,
+  label,
+}) {
+  const path = useGateway ? `/cli/tools/${functionName}` : `/functions/v1/${functionName}`;
+  const res = await callApi({
+    apiBase: useGateway ? apiBase : legacyUrl,
+    apiKey,
+    path,
+    method: 'POST',
+    body,
+    workspaceId,
+    timeoutMs,
+  });
+
+  if (res.status === 404) {
+    return { notFound: true, data: null };
+  }
+  if (!res.ok) {
+    throw await buildHttpError(res, {
+      label,
+      functionName,
+      method: 'POST',
+    });
+  }
+
+  const contentType = res.headers.get('content-type') || '';
+  if (!contentType.includes('application/json')) {
+    throw new CliError(`${label} returned a non-JSON response.`, {
+      code: 'INVALID_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
+  return { notFound: false, data: await res.json() };
+}
+
+async function readAgentToolJobStatus({
+  apiBase,
+  apiKey,
+  useGateway,
+  legacyUrl,
+  timeoutMs,
+  jobId,
+}) {
+  const response = await callToolJson({
+    apiBase,
+    apiKey,
+    useGateway,
+    legacyUrl,
+    functionName: 'agent-tool-jobs',
+    body: { action: 'status', jobId },
+    workspaceId: null,
+    timeoutMs,
+    label: 'Agent tool job status',
+  });
+  if (response.notFound) return null;
+
+  const data = response.data;
+  return {
+    kind: 'agent_tool_job',
+    id: jobId,
+    status: isJsonObject(data) ? trimString(data.status || '') : '',
+    workspaceId: isJsonObject(data) ? (data.workspaceId ?? null) : null,
+    toolName: isJsonObject(data) ? (data.toolName ?? null) : null,
+    result: isJsonObject(data) ? (data.result ?? null) : null,
+    error: isJsonObject(data) ? (data.error ?? null) : null,
+    raw: data,
+  };
+}
+
+async function readSearchJourneyRunStatus({
+  apiBase,
+  apiKey,
+  useGateway,
+  legacyUrl,
+  timeoutMs,
+  workspaceId,
+  runId,
+}) {
+  if (!workspaceId) {
+    throw new CliError('Search journey run status requires a workspace id.', {
+      code: 'WORKSPACE_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace.',
+    });
+  }
+
+  const response = await callToolJson({
+    apiBase,
+    apiKey,
+    useGateway,
+    legacyUrl,
+    functionName: 'search-journey-run',
+    body: { action: 'status', workspaceId, runId },
+    workspaceId,
+    timeoutMs,
+    label: 'Search journey status',
+  });
+  if (response.notFound) return null;
+
+  const data = response.data;
+  return {
+    kind: 'search_journey_run',
+    id: runId,
+    status: isJsonObject(data) ? trimString(data.status || '') : '',
+    workspaceId,
+    journeyId: isJsonObject(data) ? (data.journeyId ?? null) : null,
+    stagedKeywordsCount:
+      isJsonObject(data) && Array.isArray(data.stagedKeywords) ? data.stagedKeywords.length : 0,
+    error: isJsonObject(data) ? (data.error ?? null) : null,
+    raw: data,
+  };
+}
+
+async function readGoogleAiRunStatus({
+  apiBase,
+  apiKey,
+  useGateway,
+  legacyUrl,
+  timeoutMs,
+  runId,
+  includeResults,
+  resultsLimit,
+}) {
+  const runsResponse = await callToolJson({
+    apiBase,
+    apiKey,
+    useGateway,
+    legacyUrl,
+    functionName: 'get-google-ai-search-runs',
+    body: {
+      runId,
+      limit: 1,
+      offset: 0,
+    },
+    workspaceId: null,
+    timeoutMs,
+    label: 'Google AI run status',
+  });
+  if (runsResponse.notFound) return null;
+
+  const runsPayload = runsResponse.data;
+  const runItem = isJsonObject(runsPayload) && Array.isArray(runsPayload.items)
+    ? runsPayload.items.find((item) => isJsonObject(item) && Number(item.id) === runId) || null
+    : null;
+
+  if (!runItem) return null;
+
+  let resultsPayload = null;
+  if (includeResults) {
+    const resultsResponse = await callToolJson({
+      apiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      functionName: 'get-google-ai-search-results',
+      body: {
+        runId,
+        includeCitations: true,
+        limit: resultsLimit,
+        offset: 0,
+      },
+      workspaceId: null,
+      timeoutMs,
+      label: 'Google AI run results',
+    });
+    resultsPayload = resultsResponse.notFound ? null : resultsResponse.data;
+  }
+
+  return {
+    kind: 'google_ai_run',
+    id: runId,
+    status: trimString(runItem.status || ''),
+    progress: {
+      completedQueries: typeof runItem.completedQueries === 'number' ? runItem.completedQueries : null,
+      totalQueries: typeof runItem.totalQueries === 'number' ? runItem.totalQueries : null,
+      progressPercent: typeof runItem.progressPercent === 'number' ? runItem.progressPercent : null,
+    },
+    lastErrorMessage: runItem.lastErrorMessage ?? null,
+    run: runItem,
+    results: resultsPayload,
+  };
+}
+
+function buildToolStatusNotFoundError(identifier, kind, workspaceId) {
+  if (kind === 'google_ai_run') {
+    return new CliError(`Google AI run not found: ${identifier.rawId}`, {
+      code: 'STATUS_NOT_FOUND',
+      exitCode: EXIT_CODES.NOT_FOUND,
+      hint: 'Verify the run id and key scope, then retry with --kind google_ai_run.',
+    });
+  }
+  if (kind === 'agent_job') {
+    return new CliError(`Agent tool job not found: ${identifier.rawId}`, {
+      code: 'STATUS_NOT_FOUND',
+      exitCode: EXIT_CODES.NOT_FOUND,
+      hint: 'Verify the UUID job id, then retry with --kind agent_job.',
+    });
+  }
+  if (kind === 'journey_run') {
+    return new CliError(`Search journey run not found: ${identifier.rawId}`, {
+      code: 'STATUS_NOT_FOUND',
+      exitCode: EXIT_CODES.NOT_FOUND,
+      hint: 'Verify --workspace-id and the journey run UUID, then retry.',
+    });
+  }
+  return new CliError(`No matching status record found for ${identifier.rawId}.`, {
+    code: 'STATUS_NOT_FOUND',
+    exitCode: EXIT_CODES.NOT_FOUND,
+    hint: workspaceId
+      ? 'Try --kind agent_job or --kind journey_run explicitly.'
+      : 'Try --kind agent_job or provide --workspace-id to also check journey runs.',
+  });
+}
+
+async function resolveUnifiedToolStatus({
+  apiBase,
+  apiKey,
+  useGateway,
+  legacyUrl,
+  timeoutMs,
+  identifier,
+  kind,
+  workspaceId,
+  includeResults,
+  resultsLimit,
+}) {
+  if (kind === 'google_ai_run') {
+    if (identifier.numericId == null) {
+      throw new CliError('google_ai_run status expects a numeric run id.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    const result = await readGoogleAiRunStatus({
+      apiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      timeoutMs,
+      runId: identifier.numericId,
+      includeResults,
+      resultsLimit,
+    });
+    if (result) return result;
+    throw buildToolStatusNotFoundError(identifier, kind, workspaceId);
+  }
+
+  if (kind === 'agent_job') {
+    if (!identifier.uuidId) {
+      throw new CliError('agent_job status expects a UUID id.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    const result = await readAgentToolJobStatus({
+      apiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      timeoutMs,
+      jobId: identifier.uuidId,
+    });
+    if (result) return result;
+    throw buildToolStatusNotFoundError(identifier, kind, workspaceId);
+  }
+
+  if (kind === 'journey_run') {
+    if (!identifier.uuidId) {
+      throw new CliError('journey_run status expects a UUID run id.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    const result = await readSearchJourneyRunStatus({
+      apiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      timeoutMs,
+      workspaceId,
+      runId: identifier.uuidId,
+    });
+    if (result) return result;
+    throw buildToolStatusNotFoundError(identifier, kind, workspaceId);
+  }
+
+  if (identifier.numericId != null) {
+    const result = await readGoogleAiRunStatus({
+      apiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      timeoutMs,
+      runId: identifier.numericId,
+      includeResults,
+      resultsLimit,
+    });
+    if (result) return result;
+    throw buildToolStatusNotFoundError(identifier, 'google_ai_run', workspaceId);
+  }
+
+  const agentJob = await readAgentToolJobStatus({
+    apiBase,
+    apiKey,
+    useGateway,
+    legacyUrl,
+    timeoutMs,
+    jobId: identifier.uuidId,
+  });
+  if (agentJob) return agentJob;
+
+  if (workspaceId) {
+    const journeyRun = await readSearchJourneyRunStatus({
+      apiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      timeoutMs,
+      workspaceId,
+      runId: identifier.uuidId,
+    });
+    if (journeyRun) return journeyRun;
+  }
+
+  throw buildToolStatusNotFoundError(identifier, 'auto', workspaceId);
+}
+
+function buildStatusCommandHint(result, workspaceId) {
+  if (!result || !result.kind) return null;
+  if (result.kind === 'google_ai_run') {
+    return `socialseal tools status ${result.id} --kind google_ai_run`;
+  }
+  if (result.kind === 'agent_tool_job') {
+    return `socialseal tools status ${result.id} --kind agent_job`;
+  }
+  if (result.kind === 'search_journey_run') {
+    const scopedWorkspace = workspaceId || result.workspaceId;
+    if (!scopedWorkspace) return null;
+    return `socialseal tools status ${result.id} --kind journey_run --workspace-id ${scopedWorkspace}`;
+  }
+  return null;
+}
+
+function maybeEmitFollowupStatusHint({ functionName, data, workspaceId }) {
+  if (!isJsonObject(data)) return;
+  if (functionName === 'google-ai-search' && Number.isInteger(data.runId)) {
+    process.stderr.write(
+      `[socialseal] Google AI run queued: ${data.runId}. Use: socialseal tools status ${data.runId} --kind google_ai_run\n`,
+    );
+    return;
+  }
+  if (functionName === 'agent-tool-jobs' && typeof data.jobId === 'string' && isUuidLike(data.jobId)) {
+    process.stderr.write(
+      `[socialseal] Agent tool job queued: ${data.jobId}. Use: socialseal tools status ${data.jobId} --kind agent_job\n`,
+    );
+    return;
+  }
+  if (functionName === 'search-journey-run' && typeof data.runId === 'string' && isUuidLike(data.runId)) {
+    const scopedWorkspace = trimString(workspaceId || data.workspaceId || '');
+    const workspaceFlag = scopedWorkspace ? ` --workspace-id ${scopedWorkspace}` : '';
+    process.stderr.write(
+      `[socialseal] Search journey run id: ${data.runId}. Use: socialseal tools status ${data.runId} --kind journey_run${workspaceFlag}\n`,
+    );
+  }
+}
+
+async function pollUnifiedStatus({
+  loader,
+  timeoutMs,
+  pollIntervalMs,
+  opts,
+}) {
+  const deadline = Date.now() + timeoutMs;
+  let current = await loader();
+  let lastStatus = normalizeStatusValue(current?.status);
+
+  while (!isTerminalStatusValue(current?.status)) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      throw new CliError('Timed out waiting for status completion.', {
+        code: 'ASYNC_WAIT_TIMEOUT',
+        exitCode: EXIT_CODES.SERVER,
+        hint: 'Increase --timeout <ms> or omit --wait to return current status immediately.',
+        details: truncateDetails(current),
+      });
+    }
+
+    emitInfo(opts, `status: ${current.status}`);
+    await sleep(Math.min(pollIntervalMs, remainingMs));
+    current = await loader();
+    const normalized = normalizeStatusValue(current?.status);
+    if (normalized && normalized !== lastStatus) {
+      emitInfo(opts, `status: ${current.status}`);
+      lastStatus = normalized;
+    }
+  }
+
+  return current;
+}
+
 function emitError(err, opts = {}) {
   const showDetails = opts.json || opts.verbose;
   const payload = {
@@ -1812,6 +2652,18 @@ function requireApiKey(opts, config) {
   return apiKey;
 }
 
+function assertSupportedReportType(reportType) {
+  const normalized = trimString(reportType);
+  if (SUPPORTED_EXPORT_REPORT_TYPES.includes(normalized)) {
+    return normalized;
+  }
+  throw new CliError(`Unsupported report type: ${reportType}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: `Use one of: ${SUPPORTED_EXPORT_REPORT_TYPES.join(', ')}. Run \`socialseal data export-options\` to choose the right export flow.`,
+  });
+}
+
 function resolveApiTarget({ apiBase, legacyUrl }) {
   const resolvedApiBase = apiBase || (!legacyUrl ? DEFAULT_API_BASE : null);
   if (!resolvedApiBase && !legacyUrl) {
@@ -2359,6 +3211,11 @@ async function handleToolsCall(opts) {
     const data = await res.json();
     const shouldPoll = shouldHandleSearchJourneyRunAsync(opts.function, method, payload, opts) && opts.poll !== false;
     if (!shouldPoll) {
+      maybeEmitFollowupStatusHint({
+        functionName: opts.function,
+        data,
+        workspaceId: effectiveWorkspaceId,
+      });
       emitJsonOutput(data, opts.pretty);
       return;
     }
@@ -2386,9 +3243,7 @@ async function handleToolsCall(opts) {
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
-      workspaceId: isJsonObject(payload) && typeof payload.workspaceId === 'string'
-        ? payload.workspaceId
-        : resolvedWorkspaceId,
+      workspaceId: effectiveWorkspaceId,
       timeoutMs,
       pollIntervalMs: resolvePollIntervalMs(opts),
       runId,
@@ -2404,10 +3259,12 @@ async function handleToolsCall(opts) {
 }
 
 function handleToolsList(opts) {
+  const tools = buildToolRegistry();
   const payload = {
     discovery: 'built_in_registry',
-    tools: KNOWN_TOOLS,
+    tools,
     note: STATIC_TOOL_REGISTRY_NOTE,
+    schemaNote: STATIC_TOOL_SCHEMA_NOTE,
   };
 
   if (opts.json) {
@@ -2417,9 +3274,10 @@ function handleToolsList(opts) {
 
   process.stdout.write('[socialseal] Built-in tool registry\n');
   process.stdout.write(`[socialseal] ${payload.note}\n`);
+  process.stdout.write(`[socialseal] ${payload.schemaNote}\n`);
 
   let currentCategory = null;
-  for (const tool of KNOWN_TOOLS) {
+  for (const tool of tools) {
     if (tool.category !== currentCategory) {
       currentCategory = tool.category;
       process.stdout.write(`\n${currentCategory}\n`);
@@ -2434,9 +3292,148 @@ function handleToolsList(opts) {
     if (tool.notes) {
       process.stdout.write(`  note: ${tool.notes}\n`);
     }
+    if (tool.schemaAvailable) {
+      process.stdout.write(`  schema: ${tool.schemaSummary}\n`);
+      process.stdout.write(`  schema command: socialseal tools schema --function ${tool.name}\n`);
+    }
   }
 
   process.stdout.write('\n[socialseal] Call a tool with: socialseal tools call --function <name> --body @payload.json\n');
+  process.stdout.write('[socialseal] Inspect schema examples with: socialseal tools schema --function <name>\n');
+}
+
+function handleToolsSchema(opts) {
+  const tools = buildToolRegistry();
+  const functionName = trimString(opts.function || '');
+
+  if (!functionName) {
+    const payload = {
+      note: STATIC_TOOL_SCHEMA_NOTE,
+      schemas: tools
+        .filter((tool) => tool.schemaAvailable)
+        .map((tool) => ({
+          function: tool.name,
+          summary: tool.schemaSummary,
+          details: getToolSchemaHint(tool.name),
+        })),
+    };
+
+    if (opts.json) {
+      emitJsonOutput(payload, opts.pretty);
+      return;
+    }
+
+    process.stdout.write('[socialseal] Tool schema hints\n');
+    process.stdout.write(`[socialseal] ${payload.note}\n`);
+    for (const schemaEntry of payload.schemas) {
+      process.stdout.write(`- ${schemaEntry.function}: ${schemaEntry.summary}\n`);
+      process.stdout.write(`  command: socialseal tools schema --function ${schemaEntry.function}\n`);
+    }
+    return;
+  }
+
+  const knownTool = getKnownTool(functionName);
+  if (!knownTool) {
+    throw new CliError(`Unknown tool: ${functionName}`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Run `socialseal tools list` to discover available tool names.',
+    });
+  }
+
+  const schema = getToolSchemaHint(functionName);
+  if (!schema) {
+    throw new CliError(`No schema hint is bundled for ${functionName}.`, {
+      code: 'SCHEMA_NOT_AVAILABLE',
+      exitCode: EXIT_CODES.NOT_FOUND,
+      hint: 'Use `socialseal tools call --function <tool> --body @payload.json` and inspect backend validation errors for this tool.',
+    });
+  }
+
+  const payload = {
+    function: functionName,
+    note: STATIC_TOOL_SCHEMA_NOTE,
+    schema,
+  };
+
+  if (opts.json) {
+    emitJsonOutput(payload, opts.pretty);
+    return;
+  }
+
+  process.stdout.write(`[socialseal] Tool schema: ${functionName}\n`);
+  process.stdout.write(`[socialseal] ${payload.note}\n`);
+  process.stdout.write(`summary: ${schema.summary}\n`);
+  if (Array.isArray(schema.operations) && schema.operations.length > 0) {
+    process.stdout.write('operations:\n');
+    for (const operation of schema.operations) {
+      process.stdout.write(`- ${operation.action}\n`);
+      if (Array.isArray(operation.required) && operation.required.length > 0) {
+        process.stdout.write(`  required: ${operation.required.join(', ')}\n`);
+      }
+      if (Array.isArray(operation.optional) && operation.optional.length > 0) {
+        process.stdout.write(`  optional: ${operation.optional.join(', ')}\n`);
+      }
+      if (operation.notes) {
+        process.stdout.write(`  note: ${operation.notes}\n`);
+      }
+      if (operation.example) {
+        process.stdout.write(`  example body: ${JSON.stringify(operation.example)}\n`);
+      }
+    }
+  }
+  if (Array.isArray(schema.cliExamples) && schema.cliExamples.length > 0) {
+    process.stdout.write('cli examples:\n');
+    for (const example of schema.cliExamples) {
+      process.stdout.write(`- ${example}\n`);
+    }
+  }
+}
+
+async function handleToolsStatus(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 pollIntervalMs = resolvePollIntervalMs(opts);
+  const includeResults = opts.includeResults === true;
+  const resultsLimit = resolveStatusResultsLimit(opts.resultsLimit);
+  const kind = parseToolStatusKind(opts.kind);
+  const identifier = normalizeStatusIdentifier(opts.id);
+  const { workspaceId } = resolveWorkspaceSelection(opts, config);
+
+  const loadStatus = async () =>
+    await resolveUnifiedToolStatus({
+      apiBase: resolvedApiBase,
+      apiKey,
+      useGateway,
+      legacyUrl,
+      timeoutMs,
+      identifier,
+      kind,
+      workspaceId,
+      includeResults,
+      resultsLimit,
+    });
+
+  let result = await loadStatus();
+  if (opts.wait) {
+    result = await pollUnifiedStatus({
+      loader: loadStatus,
+      timeoutMs,
+      pollIntervalMs,
+      opts,
+    });
+  }
+
+  const commandHint = buildStatusCommandHint(result, workspaceId);
+  const payload = {
+    ...result,
+    hint: commandHint,
+  };
+  emitJsonOutput(payload, opts.pretty);
 }
 
 async function handleDataExportTracking(opts) {
@@ -2509,6 +3506,24 @@ async function handleDataExportTracking(opts) {
 }
 
 async function handleDataExportReport(opts) {
+  const reportType = assertSupportedReportType(opts.reportType);
+
+  if (reportType === REPORT_TYPE_SEARCH_RESULTS_ENRICHED) {
+    if (opts.format !== 'csv') {
+      throw new CliError('search_results_enriched supports only csv format.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+        hint: 'Use --format csv.',
+      });
+    }
+    const payload = ensureJsonObject(parseJsonInput(opts.payload, { label: 'payload' }), 'payload');
+    await handleDataExportSearchResults({
+      ...opts,
+      __rawPayload: payload,
+    });
+    return;
+  }
+
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
   const apiBase = resolveApiBase(opts, config);
@@ -2525,7 +3540,7 @@ async function handleDataExportReport(opts) {
     path: useGateway ? '/cli/tools/export-report' : '/functions/v1/export-report',
     method: 'POST',
     body: {
-      reportType: opts.reportType,
+      reportType,
       format: opts.format,
       payload,
     },
@@ -2571,6 +3586,142 @@ 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;
+
+  const exportResponse = await callApi({
+    apiBase: useGateway ? resolvedApiBase : legacyUrl,
+    apiKey,
+    path: useGateway ? '/cli/tools/export-data' : '/functions/v1/export-data',
+    method: 'POST',
+    body: {
+      template: EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW,
+      format: 'csv',
+      payload: normalizedPayload,
+      filename: requestedFilename,
+    },
+    workspaceId: effectiveWorkspaceId,
+    timeoutMs,
+  });
+
+  if (!exportResponse.ok) {
+    throw await buildHttpError(exportResponse, {
+      label: 'Search results enriched export',
+      functionName: 'export-data',
+      method: 'POST',
+    });
+  }
+
+  const responseJson = await exportResponse.json();
+  const metadata = isJsonObject(responseJson) && isJsonObject(responseJson.metadata)
+    ? responseJson.metadata
+    : null;
+  const fileUrl = trimString(metadata?.file_url || '');
+  const status = trimString(metadata?.status || '').toLowerCase();
+
+  if (!fileUrl) {
+    if (status === 'processing') {
+      process.stderr.write('[socialseal] Export is still processing. Re-run the same command shortly; the backend dedupes and returns the finished artifact when ready.\n');
+    } else if (status === 'failed') {
+      process.stderr.write('[socialseal] Export status is failed. Inspect the JSON metadata for details, then retry with corrected filters.\n');
+    } 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);
+    return;
+  }
+
+  const artifactResponse = await fetchWithTimeout(fileUrl, {
+    method: 'GET',
+    headers: { Accept: '*/*' },
+  }, timeoutMs);
+
+  if (!artifactResponse.ok) {
+    throw await buildHttpError(artifactResponse, {
+      label: 'Search results enriched artifact download',
+      method: 'GET',
+      hint: 'The signed file URL may be expired or inaccessible. Re-run the export command to mint a fresh URL.',
+    });
+  }
+
+  if (!artifactResponse.body) {
+    throw new CliError('Export artifact response contained no body.', {
+      code: 'EMPTY_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
+  const outPath = opts.stdout
+    ? null
+    : (opts.out || trimString(metadata?.filename || '') || 'tracking-ranked-videos.csv');
+  if (outPath) {
+    await pipeline(artifactResponse.body, fs.createWriteStream(outPath));
+    process.stderr.write(`[socialseal] Export written to ${outPath}\n`);
+  } else {
+    await pipeline(artifactResponse.body, process.stdout);
+  }
+}
+
+function handleDataExportOptions(opts) {
+  const payload = {
+    exports: EXPORT_OPTIONS,
+    supportedReportTypes: SUPPORTED_EXPORT_REPORT_TYPES,
+    note: 'Use this list to choose the right export surface before running data export commands.',
+  };
+
+  if (opts.json) {
+    emitJsonOutput(payload, opts.pretty);
+    return;
+  }
+
+  process.stdout.write('[socialseal] Available export options\n');
+  process.stdout.write('[socialseal] Choose a flow based on dataset shape, not endpoint name.\n\n');
+  for (const option of EXPORT_OPTIONS) {
+    process.stdout.write(`- ${option.id}: ${option.summary}\n`);
+    process.stdout.write(`  command: ${option.command}\n`);
+    process.stdout.write(`  formats: ${option.formats.join(', ')}\n`);
+    process.stdout.write(`  required: ${option.required.join(', ')}\n`);
+    process.stdout.write(`  best for: ${option.bestFor}\n`);
+    if (option.alias) {
+      process.stdout.write(`  alias: ${option.alias}\n`);
+    }
+    if (Array.isArray(option.reportTypes)) {
+      process.stdout.write(`  report types: ${option.reportTypes.join(', ')}\n`);
+    }
+    process.stdout.write('\n');
+  }
+}
+
 async function handleVideoExtract(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -2902,7 +4053,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 call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --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-tracking --group-id 123 --time-period 30d\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`);
 
 program
   .command('agent')
@@ -2975,6 +4126,15 @@ tools
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleToolsList, opts));
 
+tools
+  .command('schema')
+  .description('Show static payload schema hints and examples for a tool')
+  .option('--function <name>', 'Tool name (omit to list all schema hints)')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleToolsSchema, opts));
+
 tools
   .command('call')
   .requiredOption('--function <name>', 'Tool name (see official docs)')
@@ -2992,8 +4152,33 @@ tools
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleToolsCall, opts));
 
+tools
+  .command('status <id>')
+  .description('Read unified status for UUID jobs, journey run UUIDs, or numeric Google AI run ids')
+  .option('--kind <kind>', 'auto|agent_job|google_ai_run|journey_run', 'auto')
+  .option('--wait', 'Poll until status reaches a terminal state')
+  .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')
+  .option('--include-results', 'Include Google AI summary/citation rows when reading numeric run ids')
+  .option('--results-limit <n>', 'Max Google AI summary rows to include when --include-results is set')
+  .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 (required for journey_run status)')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((id, opts) => runCommand(handleToolsStatus, { ...opts, id }));
+
 const data = program.command('data').description('Data exports (provisional)');
 
+data
+  .command('export-options')
+  .description('List export flows, when to use each, and required inputs')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleDataExportOptions, opts));
+
 data
   .command('export-tracking')
   .description('Export tracking data as CSV')
@@ -3010,10 +4195,29 @@ data
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleDataExportTracking, opts));
 
+data
+  .command('export-search-results')
+  .description('Export enriched ranked search results (search_results + videos + latest metrics + analysis) as CSV')
+  .requiredOption('--group-ids <ids>', 'Comma-separated tracking group ids (for example: 123,124,125)')
+  .option('--tracking-item-ids <ids>', 'Optional comma-separated tracking item ids')
+  .option('--date-from <iso>', 'Optional ISO datetime lower bound (inclusive)')
+  .option('--date-to <iso>', 'Optional ISO datetime upper bound (inclusive)')
+  .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(handleDataExportSearchResults, opts));
+
 data
   .command('export-report')
   .description('Export report data via export-report (provisional)')
-  .requiredOption('--report-type <type>', 'keyword_universe|cluster_insights|creator_signatures|post_publish|quick_audit')
+  .requiredOption('--report-type <type>', 'keyword_universe|cluster_insights|creator_signatures|post_publish|quick_audit|search_results_enriched')
   .option('--format <format>', 'csv|json|markdown|html|excel_data', 'csv')
   .requiredOption('--payload <jsonOrFile>', 'Payload JSON or @file.json')
   .option('--out <path>', 'Output file path')