@socialseal/cli 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.1.4 - 2026-03-19
+- Add explicit `group_add_item` / `group_add_items` CLI aliases for tracking-group membership workflows.
+- Add `tracking resolve` / `get_by_value` so existing tracked searches can be resolved by value using the same duplicate-detection semantics as create.
+- Return operational duplicate metadata for tracking conflicts, including `existing_item_id`, `member_of_group_ids`, platform, region, workspace, and active state.
+
+## 0.1.3 - 2026-03-19
+- Republish the current CLI release line after the successful `0.1.2` npm publish, keeping the internal and OSS package versions aligned.
+
 ## 0.1.2 - 2026-03-18
 - Add `search-journey-run` async CLI ergonomics: `--async` starts the backend async mode, polling is on by default, and `--no-poll` returns the initial `runId` immediately.
 - Add `--poll-interval <ms>` for async `search-journey-run` status polling.

package/package.json

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

package/src/index.js

@@ -15,6 +15,7 @@ const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 300000;
 const DEFAULT_POLL_INTERVAL_MS = 2000;
 const MAX_TIMEOUT_MS = 900000;
 const LEGACY_ENABLED = process.env.SOCIALSEAL_ENABLE_LEGACY === '1';
+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 EXIT_CODES = {
   OK: 0,
   UNKNOWN: 1,
@@ -29,18 +30,66 @@ const KNOWN_TOOLS = [
   { 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.' },
-  { name: 'brand-group-management', category: 'brand', description: 'Manage brand groups, aliases, competitors, and rule configuration.' },
-  { name: 'enqueue-brand-metrics-backfill', category: 'brand', description: 'Queue backfill jobs for brand metrics refreshes.' },
+  {
+    name: 'brand-group-management',
+    category: 'brand',
+    description: 'Manage brand groups, aliases, competitors, and rule configuration.',
+    objectType: 'brand_group',
+    transport: 'rest_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'create', 'update', 'delete', 'add_member', 'remove_member'],
+    notes: 'Brand groups are not tracking groups.',
+  },
+  {
+    name: 'enqueue-brand-metrics-backfill',
+    category: 'brand',
+    description: 'Queue backfill jobs for brand metrics refreshes.',
+    objectType: 'brand_metrics_backfill_job',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    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_tracking_data', category: 'export', description: 'Stream tracking exports as CSV for a group or tracking item.' },
+  {
+    name: 'export_tracking_data',
+    category: 'export',
+    description: 'Stream tracking exports as CSV for a group or tracking item.',
+    objectType: 'tracking_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'disabled_by_default',
+    notes: 'group_id expects a numeric tracking_group id, not a brand_group UUID.',
+  },
   { 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: '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.' },
   { name: 'youtube-geo-api', category: 'search', description: 'Query YouTube search and geo data.' },
-  { name: 'group-management', category: 'tracking', description: 'Create, update, list, and delete tracking groups and memberships.' },
-  { name: 'tracking', category: 'tracking', description: 'Create, update, list, refresh, and delete tracking items.' },
+  {
+    name: 'group-management',
+    category: 'tracking',
+    description: 'Manage tracking groups and memberships.',
+    objectType: 'tracking_group',
+    transport: 'rest_edge_function',
+    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.',
+  },
+  {
+    name: 'tracking',
+    category: 'tracking',
+    description: 'Manage tracking items.',
+    objectType: 'tracking_item',
+    transport: 'rest_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'get', 'resolve', 'get_by_value', 'create', 'update', 'delete', 'refresh'],
+    notes: 'REST-style surface. `resolve`/`get_by_value` uses the same workspace/platform/region duplicate-detection lookup as create and returns inactive matches too.',
+  },
   { 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.' },
@@ -290,10 +339,869 @@ function mergeWorkspaceIdIntoPayload(payload, workspaceId) {
   return { ...payload, workspaceId };
 }
 
+function hasOwn(value, key) {
+  return Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function firstDefined(source, keys) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) return undefined;
+  for (const key of keys) {
+    if (hasOwn(source, key) && source[key] !== undefined && source[key] !== null) {
+      return source[key];
+    }
+  }
+  return undefined;
+}
+
+function trimString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function stripUndefinedEntries(value) {
+  return Object.fromEntries(
+    Object.entries(value || {}).filter(([, entry]) => entry !== undefined),
+  );
+}
+
+function resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) {
+  const workspaceId = firstDefined(payload, ['workspace_id', 'workspaceId']);
+  if (typeof workspaceId === 'string' && workspaceId.trim().length > 0) {
+    return workspaceId.trim();
+  }
+  return fallbackWorkspaceId || null;
+}
+
+function isUuidLike(value) {
+  return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.trim());
+}
+
+function coercePositiveInteger(value, label) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const parsed = Number(value);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  throw new CliError(`Invalid ${label}: expected a positive integer.`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: isUuidLike(value)
+      ? `${label} expects a numeric tracking id. Brand-group ids are UUIDs and use brand-group-management instead.`
+      : null,
+    details: value,
+  });
+}
+
+function buildPathWithQuery(basePath, query) {
+  const params = new URLSearchParams();
+  for (const [key, rawValue] of Object.entries(query || {})) {
+    if (rawValue === undefined || rawValue === null || rawValue === '') continue;
+    if (Array.isArray(rawValue)) {
+      for (const entry of rawValue) {
+        if (entry !== undefined && entry !== null && entry !== '') {
+          params.append(key, String(entry));
+        }
+      }
+      continue;
+    }
+    params.set(key, String(rawValue));
+  }
+  const queryString = params.toString();
+  return queryString ? `${basePath}?${queryString}` : basePath;
+}
+
+function normalizeTrackingType(value) {
+  const normalized = trimString(value).toLowerCase();
+  if (!normalized) return undefined;
+  if (normalized === 'keyword' || normalized === 'search') return 'search';
+  if (normalized === 'account' || normalized === 'creator') return 'creator';
+  if (normalized === 'hashtag') return 'hashtag';
+  throw new CliError(`Invalid tracking type: ${value}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use keyword/search, hashtag, or account/creator.',
+  });
+}
+
+function normalizeTrackingPayload(payload, fallbackWorkspaceId) {
+  const trackValue = firstDefined(payload, ['track_value', 'trackValue', 'value']);
+  const refreshFrequency = firstDefined(payload, ['refresh_frequency', 'refreshFrequency']);
+  const nextRefreshAt = firstDefined(payload, ['next_refresh_at', 'nextRefreshAt']);
+  const region = firstDefined(payload, ['region']);
+  const platform = firstDefined(payload, ['platform']);
+  const brandIds = firstDefined(payload, ['brand_ids', 'brandIds']);
+  const includeInactive = firstDefined(payload, ['includeInactive', 'include_inactive']);
+  const isActive = firstDefined(payload, ['is_active', 'isActive']);
+  const limit = firstDefined(payload, ['limit']);
+  const page = firstDefined(payload, ['page']);
+  const offset = firstDefined(payload, ['offset']);
+  const itemId = firstDefined(payload, ['item_id', 'itemId', 'id']);
+
+  return stripUndefinedEntries({
+    action: trimString(firstDefined(payload, ['action'])) || undefined,
+    workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
+    item_id: coercePositiveInteger(itemId, 'item_id'),
+    name: trimString(firstDefined(payload, ['name'])) || (trimString(trackValue) || undefined),
+    track_type: normalizeTrackingType(firstDefined(payload, ['track_type', 'trackType', 'type'])),
+    track_value: trimString(trackValue) || undefined,
+    refresh_frequency: trimString(refreshFrequency) || undefined,
+    next_refresh_at: nextRefreshAt ?? undefined,
+    region: typeof region === 'string' ? region.trim() || undefined : region,
+    platform: trimString(platform) || undefined,
+    brand_ids: Array.isArray(brandIds) ? brandIds : undefined,
+    limit: limit !== undefined ? Number(limit) : undefined,
+    page: page !== undefined ? Number(page) : undefined,
+    offset: offset !== undefined ? Number(offset) : undefined,
+    is_active: typeof isActive === 'boolean' ? isActive : undefined,
+    include_inactive: typeof includeInactive === 'boolean' ? includeInactive : undefined,
+  });
+}
+
+function normalizeGroupManagementPayload(payload, fallbackWorkspaceId) {
+  const groupId = firstDefined(payload, ['group_id', 'groupId', 'id']);
+  const itemId = firstDefined(payload, ['item_id', 'itemId']);
+  const itemIds = firstDefined(payload, ['item_ids', 'itemIds']);
+  const items = firstDefined(payload, ['items']);
+  const limit = firstDefined(payload, ['limit']);
+  const page = firstDefined(payload, ['page']);
+  return stripUndefinedEntries({
+    action: trimString(firstDefined(payload, ['action'])) || undefined,
+    workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
+    group_id: coercePositiveInteger(groupId, 'group_id'),
+    item_id: coercePositiveInteger(itemId, 'item_id'),
+    item_ids: Array.isArray(itemIds)
+      ? itemIds.map((value, index) => {
+        const parsed = coercePositiveInteger(value, `item_ids[${index}]`);
+        if (!parsed) {
+          throw new CliError(`Invalid item_ids[${index}]: expected a positive integer.`, {
+            code: 'INVALID_ARGUMENT',
+            exitCode: EXIT_CODES.USAGE,
+          });
+        }
+        return parsed;
+      })
+      : undefined,
+    items: Array.isArray(items) ? items : undefined,
+    name: trimString(firstDefined(payload, ['name'])) || undefined,
+    description: firstDefined(payload, ['description']),
+    platform: trimString(firstDefined(payload, ['platform', 'groupPlatform'])) || undefined,
+    refresh_frequency: trimString(firstDefined(payload, ['refresh_frequency', 'refreshFrequency'])) || undefined,
+    next_refresh_at: firstDefined(payload, ['next_refresh_at', 'nextRefreshAt']) ?? undefined,
+    brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    track_type: normalizeTrackingType(firstDefined(payload, ['track_type', 'trackType', 'type'])),
+    track_value: trimString(firstDefined(payload, ['track_value', 'trackValue', 'value'])) || undefined,
+    region: typeof firstDefined(payload, ['region']) === 'string'
+      ? trimString(firstDefined(payload, ['region'])) || undefined
+      : firstDefined(payload, ['region']),
+    limit: limit !== undefined ? Number(limit) : undefined,
+    page: page !== undefined ? Number(page) : undefined,
+  });
+}
+
+function normalizeBrandGroupPayload(payload, fallbackWorkspaceId) {
+  return stripUndefinedEntries({
+    action: trimString(firstDefined(payload, ['action'])) || undefined,
+    workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
+    workspace_id: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) || undefined,
+    brand_group_id: trimString(firstDefined(payload, ['brand_group_id', 'brandGroupId', 'group_id', 'groupId', 'id'])) || undefined,
+    brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    name: trimString(firstDefined(payload, ['name'])) || undefined,
+    description: firstDefined(payload, ['description']),
+  });
+}
+
+function normalizeBackfillPayload(payload, fallbackWorkspaceId) {
+  return stripUndefinedEntries({
+    workspace_id: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) || undefined,
+    brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    tracking_group_ids: firstDefined(payload, ['tracking_group_ids', 'trackingGroupIds']),
+    backfill_days: firstDefined(payload, ['backfill_days', 'backfillDays']),
+    max_tracking_groups: firstDefined(payload, ['max_tracking_groups', 'maxTrackingGroups']),
+    max_videos: firstDefined(payload, ['max_videos', 'maxVideos']),
+    max_summaries: firstDefined(payload, ['max_summaries', 'maxSummaries']),
+    bump_user_revision: firstDefined(payload, ['bump_user_revision', 'bumpUserRevision']),
+    bump_workspace_revision: firstDefined(payload, ['bump_workspace_revision', 'bumpWorkspaceRevision']),
+  });
+}
+
+function normalizeTrackingExportPayload(payload, fallbackWorkspaceId) {
+  const groupId = firstDefined(payload, ['group_id', 'groupId', 'tracking_group_id', 'trackingGroupId']);
+  const itemId = firstDefined(payload, ['tracking_item_id', 'trackingItemId', 'item_id', 'itemId']);
+  return stripUndefinedEntries({
+    workspace_id: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) || undefined,
+    group_id: coercePositiveInteger(groupId, 'group_id'),
+    tracking_item_id: coercePositiveInteger(itemId, 'tracking_item_id'),
+    time_period: trimString(firstDefined(payload, ['time_period', 'timePeriod'])) || undefined,
+  });
+}
+
+function buildGroupAddPayloadFromValue(rawValue, payload, label) {
+  const value = trimString(rawValue);
+  if (!value) {
+    throw new CliError(`Invalid ${label}: expected a non-empty tracking value.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  if (!payload.track_type) {
+    throw new CliError(`${label} requires track_type/type when using raw values.`, {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use type=keyword/search, hashtag, or account/creator when adding items by value.',
+    });
+  }
+  return stripUndefinedEntries({
+    name: value,
+    track_type: payload.track_type,
+    track_value: value,
+    refresh_frequency: payload.refresh_frequency,
+    next_refresh_at: payload.next_refresh_at,
+    region: payload.region,
+    platform: payload.platform,
+  });
+}
+
+function buildGroupAddPayloadFromItem(rawItem, payload, label) {
+  if (typeof rawItem === 'number') {
+    return { item_id: coercePositiveInteger(rawItem, label) };
+  }
+
+  if (typeof rawItem === 'string') {
+    const trimmed = rawItem.trim();
+    if (/^\d+$/.test(trimmed)) {
+      return { item_id: coercePositiveInteger(trimmed, label) };
+    }
+    return buildGroupAddPayloadFromValue(rawItem, payload, label);
+  }
+
+  if (!rawItem || typeof rawItem !== 'object' || Array.isArray(rawItem)) {
+    throw new CliError(`Invalid ${label}: expected an item id, string value, or object payload.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+
+  const itemId = coercePositiveInteger(firstDefined(rawItem, ['item_id', 'itemId', 'id']), `${label}.item_id`);
+  if (itemId) {
+    return { item_id: itemId };
+  }
+
+  const trackValue = trimString(firstDefined(rawItem, ['track_value', 'trackValue', 'value'])) || undefined;
+  const name = trimString(firstDefined(rawItem, ['name'])) || trackValue;
+  const trackType = normalizeTrackingType(firstDefined(rawItem, ['track_type', 'trackType', 'type'])) || payload.track_type;
+  const region = firstDefined(rawItem, ['region']) ?? payload.region;
+  const platform = trimString(firstDefined(rawItem, ['platform'])) || payload.platform;
+  const refreshFrequency = trimString(firstDefined(rawItem, ['refresh_frequency', 'refreshFrequency'])) || payload.refresh_frequency;
+  const nextRefreshAt = firstDefined(rawItem, ['next_refresh_at', 'nextRefreshAt']) ?? payload.next_refresh_at;
+
+  if (!name || !trackValue || !trackType) {
+    throw new CliError(`${label} requires item_id or name/track_value + track_type.`, {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+
+  return stripUndefinedEntries({
+    name,
+    track_type: trackType,
+    track_value: trackValue,
+    refresh_frequency: refreshFrequency,
+    next_refresh_at: nextRefreshAt,
+    region,
+    platform,
+  });
+}
+
+function buildSingleGroupAddBody(payload) {
+  if (payload.item_id) {
+    return { item_id: payload.item_id };
+  }
+  if (payload.track_value || payload.name) {
+    return buildGroupAddPayloadFromItem({
+      name: payload.name,
+      track_type: payload.track_type,
+      track_value: payload.track_value,
+      refresh_frequency: payload.refresh_frequency,
+      next_refresh_at: payload.next_refresh_at,
+      region: payload.region,
+      platform: payload.platform,
+    }, payload, 'group add item payload');
+  }
+  throw new CliError('group add_item requires item_id or a tracking payload.', {
+    code: 'MISSING_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Provide item_id to attach an existing tracking item, or provide track_type + track_value to create/link by value.',
+  });
+}
+
+function buildBulkGroupAddBody(payload) {
+  if (Array.isArray(payload.item_ids) && payload.item_ids.length > 0) {
+    return payload.item_ids.map((item_id) => ({ item_id }));
+  }
+  if (Array.isArray(payload.items) && payload.items.length > 0) {
+    return payload.items.map((item, index) => buildGroupAddPayloadFromItem(item, payload, `items[${index}]`));
+  }
+  if (payload.item_id || payload.track_value || payload.name) {
+    return [buildSingleGroupAddBody(payload)];
+  }
+  throw new CliError('group add_items requires item_ids, items, or a single item payload.', {
+    code: 'MISSING_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use item_ids to bulk attach existing tracking items, or use items with track_type/type for value-based adds.',
+  });
+}
+
+function translateTrackingAction(payload, workspaceId) {
+  const action = payload.action ? payload.action.toLowerCase() : null;
+  if (!action) {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        region: payload.region,
+        platform: payload.platform,
+        brand_ids: payload.brand_ids,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'list' || action === 'item_list') {
+    const limit = Number.isFinite(payload.limit) ? payload.limit : 20;
+    const page = Number.isFinite(payload.page) ? Math.max(1, payload.page) : 1;
+    const offset = Number.isFinite(payload.offset) ? Math.max(0, payload.offset) : ((page - 1) * limit);
+    const isActive = typeof payload.is_active === 'boolean'
+      ? payload.is_active
+      : (payload.include_inactive ? undefined : true);
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('', {
+        workspace_id: workspaceId || undefined,
+        limit,
+        offset,
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        platform: payload.platform,
+        region: payload.region,
+        is_active: isActive,
+      }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'get' || action === 'item_get') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking get.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery(`/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'resolve' || action === 'item_resolve' || action === 'get_by_value' || action === 'item_get_by_value') {
+    if (!payload.track_type || !payload.track_value) {
+      throw new CliError('track_type and track_value are required for tracking resolve.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('', {
+        workspace_id: workspaceId || undefined,
+        resolve: 'true',
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        platform: payload.platform,
+        region: payload.region,
+      }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'create' || action === 'item_create') {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        region: payload.region,
+        platform: payload.platform,
+        brand_ids: payload.brand_ids,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'update' || action === 'item_update') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking update.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'PATCH',
+      pathSuffix: buildPathWithQuery(`/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'delete' || action === 'item_delete') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking delete.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: buildPathWithQuery(`/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'refresh' || action === 'item_refresh') {
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!itemId) {
+      throw new CliError('item_id is required for tracking refresh.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/${itemId}/refresh`, { workspace_id: workspaceId || undefined }),
+      body: {},
+      workspaceId,
+    };
+  }
+
+  throw new CliError(`Unsupported tracking action: ${payload.action}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Supported tracking actions: list, get, resolve, create, update, delete, refresh.',
+  });
+}
+
+function translateGroupManagementAction(payload, workspaceId, originalMethod) {
+  const action = payload.action ? payload.action.toLowerCase() : null;
+
+  if (!action && originalMethod === 'GET') {
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (!action) {
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        platform: payload.platform,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        brand_id: payload.brand_id,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'list' || action === 'group_list') {
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'get' || action === 'group_get') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group get.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'create' || action === 'group_create') {
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery('/groups', { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        platform: payload.platform,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        brand_id: payload.brand_id,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'update' || action === 'group_update') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group update.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'PATCH',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}`, { workspace_id: workspaceId || undefined }),
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        refresh_frequency: payload.refresh_frequency,
+        next_refresh_at: payload.next_refresh_at,
+        brand_id: payload.brand_id,
+      }),
+      workspaceId,
+    };
+  }
+
+  if (action === 'delete' || action === 'group_delete') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group delete.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'refresh' || action === 'group_refresh') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group refresh.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/refresh`, { workspace_id: workspaceId || undefined }),
+      body: {},
+      workspaceId,
+    };
+  }
+
+  if (action === 'list_items' || action === 'group_list_items') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group list_items.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items`, {
+        workspace_id: workspaceId || undefined,
+        page: Number.isFinite(payload.page) ? payload.page : undefined,
+        limit: Number.isFinite(payload.limit) ? payload.limit : undefined,
+      }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  if (action === 'add_item' || action === 'group_add_item') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group add_item.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items`, { workspace_id: workspaceId || undefined }),
+      body: buildSingleGroupAddBody(payload),
+      workspaceId,
+    };
+  }
+
+  if (action === 'add_items' || action === 'group_add_items') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group add_items.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items/bulk`, { workspace_id: workspaceId || undefined }),
+      body: buildBulkGroupAddBody(payload),
+      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');
+    if (!groupId || !itemId) {
+      throw new CliError('group_id and item_id are required for group remove_item.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
+  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.',
+  });
+}
+
+function translateBrandGroupAction(payload, workspaceId) {
+  const action = payload.action ? payload.action.toLowerCase() : null;
+  const brandGroupId = payload.brand_group_id || undefined;
+  const effectiveWorkspaceId = payload.workspace_id || workspaceId || undefined;
+
+  if (!action) {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        workspace_id: effectiveWorkspaceId,
+      }),
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'list') {
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('', { workspace_id: effectiveWorkspaceId }),
+      body: undefined,
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'create') {
+    return {
+      method: 'POST',
+      pathSuffix: '',
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+        workspace_id: effectiveWorkspaceId,
+      }),
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'update') {
+    if (!brandGroupId) {
+      throw new CliError('brand_group_id is required for brand-group update.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'PATCH',
+      pathSuffix: `/${brandGroupId}`,
+      body: stripUndefinedEntries({
+        name: payload.name,
+        description: payload.description,
+      }),
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'delete') {
+    if (!brandGroupId) {
+      throw new CliError('brand_group_id is required for brand-group delete.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: `/${brandGroupId}`,
+      body: undefined,
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'add_member') {
+    if (!brandGroupId || !payload.brand_id) {
+      throw new CliError('brand_group_id and brand_id are required for brand-group add_member.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: `/${brandGroupId}/members`,
+      body: { brand_id: payload.brand_id },
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  if (action === 'remove_member') {
+    if (!brandGroupId || !payload.brand_id) {
+      throw new CliError('brand_group_id and brand_id are required for brand-group remove_member.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: `/${brandGroupId}/members/${payload.brand_id}`,
+      body: undefined,
+      workspaceId: workspaceId || null,
+    };
+  }
+
+  throw new CliError(`Unsupported brand-group-management action: ${payload.action}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Supported brand-group-management actions: list, create, update, delete, add_member, remove_member.',
+  });
+}
+
+function translateToolInvocation({ functionName, method, payload, resolvedWorkspaceId }) {
+  if (!isJsonObject(payload)) {
+    return {
+      method,
+      pathSuffix: '',
+      body: payload,
+      workspaceId: resolvedWorkspaceId,
+      normalizedPayload: payload,
+    };
+  }
+
+  if (functionName === 'tracking') {
+    const normalizedPayload = normalizeTrackingPayload(payload, resolvedWorkspaceId);
+    const workspaceId = normalizedPayload.workspaceId || resolvedWorkspaceId || null;
+    const translated = translateTrackingAction(normalizedPayload, workspaceId);
+    return { ...translated, normalizedPayload };
+  }
+
+  if (functionName === 'group-management') {
+    const normalizedPayload = normalizeGroupManagementPayload(payload, resolvedWorkspaceId);
+    const workspaceId = normalizedPayload.workspaceId || resolvedWorkspaceId || null;
+    const translated = translateGroupManagementAction(normalizedPayload, workspaceId, method);
+    return { ...translated, normalizedPayload };
+  }
+
+  if (functionName === 'brand-group-management') {
+    const normalizedPayload = normalizeBrandGroupPayload(payload, resolvedWorkspaceId);
+    const workspaceId = normalizedPayload.workspaceId || resolvedWorkspaceId || null;
+    const translated = translateBrandGroupAction(normalizedPayload, workspaceId);
+    return { ...translated, normalizedPayload };
+  }
+
+  if (functionName === 'enqueue-brand-metrics-backfill') {
+    const normalizedPayload = normalizeBackfillPayload(payload, resolvedWorkspaceId);
+    if (!normalizedPayload.brand_id && hasOwn(payload, 'group_id')) {
+      throw new CliError('enqueue-brand-metrics-backfill expects brand_id, not group_id.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+        hint: 'Use group-management refresh for tracking groups. Backfill jobs refresh brand metrics for a workspace brand.',
+      });
+    }
+    return {
+      method,
+      pathSuffix: '',
+      body: normalizedPayload,
+      workspaceId: resolvedWorkspaceId,
+      normalizedPayload,
+    };
+  }
+
+  if (functionName === 'export_tracking_data') {
+    const normalizedPayload = normalizeTrackingExportPayload(payload, resolvedWorkspaceId);
+    return {
+      method,
+      pathSuffix: '',
+      body: normalizedPayload,
+      workspaceId: normalizedPayload.workspace_id || resolvedWorkspaceId || null,
+      normalizedPayload,
+    };
+  }
+
+  return {
+    method,
+    pathSuffix: '',
+    body: payload,
+    workspaceId: resolvedWorkspaceId,
+    normalizedPayload: payload,
+  };
+}
+
 function isJsonObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
+function isStateChangingMethod(method) {
+  return !['GET', 'HEAD', 'OPTIONS'].includes(method);
+}
+
+function emitWorkspaceContext(opts, { workspaceId, source, functionName, method }) {
+  if (!workspaceId || !isStateChangingMethod(method)) return;
+  process.stderr.write(
+    `[socialseal] Workspace: ${workspaceId}${source ? ` (${source})` : ''} for ${functionName} ${method}\n`,
+  );
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -431,6 +1339,10 @@ function mapStatusToExitCode(status) {
   return EXIT_CODES.UNKNOWN;
 }
 
+function isLocallyDisabledByDefaultFunction(functionName) {
+  return functionName === 'group-management' || functionName === 'export_tracking_data';
+}
+
 function buildStatusHint(status, context = {}) {
   switch (status) {
     case 401:
@@ -438,13 +1350,16 @@ function buildStatusHint(status, context = {}) {
       return 'Check your CLI key and workspace access.';
     case 404:
       if (context.functionName) {
+        if (isLocallyDisabledByDefaultFunction(context.functionName)) {
+          return `Unknown function "${context.functionName}". This tool is listed in the static registry, but it is disabled by default in some local Supabase environments. Check the deployment or enable it in supabase/config.toml.`;
+        }
         return `Unknown function "${context.functionName}". Double-check the name and API base.`;
       }
       return 'Check the API base URL and endpoint path.';
     case 405:
       return `Method not allowed. Try --method GET or ensure the endpoint supports ${context.method || 'this method'}.`;
     case 422:
-      return 'Validation error. Review the JSON payload schema.';
+      return 'Validation error. Review the JSON payload schema. For tracking/group tools, prefer the CLI action aliases or the documented REST semantics.';
     default:
       return null;
   }
@@ -991,19 +1906,38 @@ async function handleToolsCall(opts) {
   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 } = resolveWorkspaceSelection(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
 
   const parsedPayload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
   const mergedPayload = mergeWorkspaceIdIntoPayload(parsedPayload, resolvedWorkspaceId);
-  const method = normalizeMethod(opts.method);
-  const payload = applySearchJourneyRunAsyncStart(mergedPayload, { ...opts, method });
+  const requestedMethod = normalizeMethod(opts.method);
+  const payload = applySearchJourneyRunAsyncStart(mergedPayload, { ...opts, method: requestedMethod });
+  const translated = translateToolInvocation({
+    functionName: opts.function,
+    method: requestedMethod,
+    payload,
+    resolvedWorkspaceId,
+  });
+  const method = normalizeMethod(translated.method);
+  const effectiveWorkspaceId = translated.workspaceId ?? resolvedWorkspaceId ?? null;
+  const path = useGateway
+    ? `/cli/tools/${opts.function}${translated.pathSuffix || ''}`
+    : `/functions/v1/${opts.function}${translated.pathSuffix || ''}`;
+
+  emitWorkspaceContext(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    functionName: opts.function,
+    method,
+  });
+
   const res = await callApi({
     apiBase: useGateway ? resolvedApiBase : legacyUrl,
     apiKey,
-    path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
+    path,
     method,
-    body: payload,
-    workspaceId: resolvedWorkspaceId,
+    body: translated.body,
+    workspaceId: effectiveWorkspaceId,
     timeoutMs,
   });
 
@@ -1068,7 +2002,7 @@ function handleToolsList(opts) {
   const payload = {
     discovery: 'built_in_registry',
     tools: KNOWN_TOOLS,
-    note: 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration.',
+    note: STATIC_TOOL_REGISTRY_NOTE,
   };
 
   if (opts.json) {
@@ -1085,7 +2019,16 @@ function handleToolsList(opts) {
       currentCategory = tool.category;
       process.stdout.write(`\n${currentCategory}\n`);
     }
-    process.stdout.write(`- ${tool.name}: ${tool.description}\n`);
+    const qualifiers = [
+      tool.objectType ? `object=${tool.objectType}` : null,
+      tool.transport ? `transport=${tool.transport}` : null,
+      tool.knownLocalDevState ? `local=${tool.knownLocalDevState}` : null,
+    ].filter(Boolean);
+    const qualifierText = qualifiers.length > 0 ? ` [${qualifiers.join(', ')}]` : '';
+    process.stdout.write(`- ${tool.name}${qualifierText}: ${tool.description}\n`);
+    if (tool.notes) {
+      process.stdout.write(`  note: ${tool.notes}\n`);
+    }
   }
 
   process.stdout.write('\n[socialseal] Call a tool with: socialseal tools call --function <name> --body @payload.json\n');
@@ -1107,6 +2050,13 @@ async function handleDataExportTracking(opts) {
     });
   }
 
+  if (opts.groupId !== undefined) {
+    opts.groupId = coercePositiveInteger(opts.groupId, 'group_id');
+  }
+  if (opts.itemId !== undefined) {
+    opts.itemId = coercePositiveInteger(opts.itemId, 'tracking_item_id');
+  }
+
   const payload = {
     tracking_item_id: opts.itemId || undefined,
     group_id: opts.groupId || undefined,