@cliangdev/conductor 0.51.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/assets/claude/agents/conductor-marketing-art-director.md +2 -1
  2. package/assets/claude/skills/conductor-marketing-create/SKILL.md +12 -2
  3. package/assets/claude/skills/conductor-marketing-create/references/capabilities.md +9 -2
  4. package/assets/claude/skills/conductor-marketing-create/references/direct.md +39 -6
  5. package/assets/claude/skills/conductor-marketing-create/references/platform-specs.md +15 -4
  6. package/assets/claude/skills/conductor-marketing-create/references/shotlist-template.md +2 -2
  7. package/assets/claude/skills/conductor-marketing-create/references/slideshow-formats.md +2 -1
  8. package/assets/claude/skills/conductor-marketing-create/references/team-run.md +3 -3
  9. package/assets/claude/skills/conductor-marketing-report/SKILL.md +2 -2
  10. package/assets/cli-manifest.json +261 -23
  11. package/dist/creative/assertions.js +30 -3
  12. package/dist/creative/frame.js +2 -2
  13. package/dist/creative/job/media.mjs +2 -2
  14. package/dist/creative/job/render.mjs +3 -0
  15. package/dist/creative/placements.js +2 -2
  16. package/dist/creative/placements.json +3 -3
  17. package/dist/creative/render.js +20 -8
  18. package/dist/lib/creative-render.d.ts +14 -1
  19. package/dist/lib/creative-render.d.ts.map +1 -1
  20. package/dist/lib/creative-render.js +3 -1
  21. package/dist/lib/creative-render.js.map +1 -1
  22. package/dist/lib/safe-zone/check.d.ts +31 -0
  23. package/dist/lib/safe-zone/check.d.ts.map +1 -0
  24. package/dist/lib/safe-zone/check.js +267 -0
  25. package/dist/lib/safe-zone/check.js.map +1 -0
  26. package/dist/lib/safe-zone/frames.d.ts +35 -0
  27. package/dist/lib/safe-zone/frames.d.ts.map +1 -0
  28. package/dist/lib/safe-zone/frames.js +132 -0
  29. package/dist/lib/safe-zone/frames.js.map +1 -0
  30. package/dist/lib/safe-zone/ocr.d.ts +42 -0
  31. package/dist/lib/safe-zone/ocr.d.ts.map +1 -0
  32. package/dist/lib/safe-zone/ocr.js +139 -0
  33. package/dist/lib/safe-zone/ocr.js.map +1 -0
  34. package/dist/lib/safe-zone/overlay.d.ts +59 -0
  35. package/dist/lib/safe-zone/overlay.d.ts.map +1 -0
  36. package/dist/lib/safe-zone/overlay.js +283 -0
  37. package/dist/lib/safe-zone/overlay.js.map +1 -0
  38. package/dist/lib/safe-zone/zones.d.ts +46 -0
  39. package/dist/lib/safe-zone/zones.d.ts.map +1 -0
  40. package/dist/lib/safe-zone/zones.js +84 -0
  41. package/dist/lib/safe-zone/zones.js.map +1 -0
  42. package/dist/lib/slideshow/compose.d.ts +2 -0
  43. package/dist/lib/slideshow/compose.d.ts.map +1 -1
  44. package/dist/lib/slideshow/compose.js +1 -1
  45. package/dist/lib/slideshow/compose.js.map +1 -1
  46. package/dist/lib/slideshow/css.d.ts +2 -0
  47. package/dist/lib/slideshow/css.d.ts.map +1 -1
  48. package/dist/lib/slideshow/css.js +9 -5
  49. package/dist/lib/slideshow/css.js.map +1 -1
  50. package/dist/lib/slideshow/html.d.ts +12 -3
  51. package/dist/lib/slideshow/html.d.ts.map +1 -1
  52. package/dist/lib/slideshow/html.js +16 -10
  53. package/dist/lib/slideshow/html.js.map +1 -1
  54. package/dist/lib/slideshow/spec-transport.d.ts.map +1 -1
  55. package/dist/lib/slideshow/spec-transport.js +4 -2
  56. package/dist/lib/slideshow/spec-transport.js.map +1 -1
  57. package/dist/lib/slideshow/spec.d.ts +8 -0
  58. package/dist/lib/slideshow/spec.d.ts.map +1 -1
  59. package/dist/lib/slideshow/spec.js +6 -0
  60. package/dist/lib/slideshow/spec.js.map +1 -1
  61. package/dist/lib/slideshow-pacing.d.ts +46 -0
  62. package/dist/lib/slideshow-pacing.d.ts.map +1 -0
  63. package/dist/lib/slideshow-pacing.js +98 -0
  64. package/dist/lib/slideshow-pacing.js.map +1 -0
  65. package/dist/mcp/index.d.ts +12023 -800
  66. package/dist/mcp/index.d.ts.map +1 -1
  67. package/dist/mcp/index.js +593 -13
  68. package/dist/mcp/index.js.map +1 -1
  69. package/dist/mcp/tools/ai-visibility.d.ts +18 -0
  70. package/dist/mcp/tools/ai-visibility.d.ts.map +1 -0
  71. package/dist/mcp/tools/ai-visibility.js +124 -0
  72. package/dist/mcp/tools/ai-visibility.js.map +1 -0
  73. package/dist/mcp/tools/budget.d.ts +35 -0
  74. package/dist/mcp/tools/budget.d.ts.map +1 -0
  75. package/dist/mcp/tools/budget.js +205 -0
  76. package/dist/mcp/tools/budget.js.map +1 -0
  77. package/dist/mcp/tools/creative-drafts.d.ts +16 -2
  78. package/dist/mcp/tools/creative-drafts.d.ts.map +1 -1
  79. package/dist/mcp/tools/creative-drafts.js +237 -31
  80. package/dist/mcp/tools/creative-drafts.js.map +1 -1
  81. package/dist/mcp/tools/creatives.d.ts +12 -3
  82. package/dist/mcp/tools/creatives.d.ts.map +1 -1
  83. package/dist/mcp/tools/creatives.js +235 -17
  84. package/dist/mcp/tools/creatives.js.map +1 -1
  85. package/dist/mcp/tools/creators.d.ts +15 -0
  86. package/dist/mcp/tools/creators.d.ts.map +1 -0
  87. package/dist/mcp/tools/creators.js +69 -0
  88. package/dist/mcp/tools/creators.js.map +1 -0
  89. package/dist/mcp/tools/growth-signals.d.ts +38 -0
  90. package/dist/mcp/tools/growth-signals.d.ts.map +1 -0
  91. package/dist/mcp/tools/growth-signals.js +135 -0
  92. package/dist/mcp/tools/growth-signals.js.map +1 -0
  93. package/dist/mcp/tools/insights.d.ts +9 -0
  94. package/dist/mcp/tools/insights.d.ts.map +1 -1
  95. package/dist/mcp/tools/insights.js +6 -1
  96. package/dist/mcp/tools/insights.js.map +1 -1
  97. package/dist/mcp/tools/links.d.ts +26 -0
  98. package/dist/mcp/tools/links.d.ts.map +1 -0
  99. package/dist/mcp/tools/links.js +92 -0
  100. package/dist/mcp/tools/links.js.map +1 -0
  101. package/dist/mcp/tools/marketing-changes.d.ts +25 -0
  102. package/dist/mcp/tools/marketing-changes.d.ts.map +1 -0
  103. package/dist/mcp/tools/marketing-changes.js +108 -0
  104. package/dist/mcp/tools/marketing-changes.js.map +1 -0
  105. package/dist/mcp/tools/marketing-definitions.d.ts +11 -0
  106. package/dist/mcp/tools/marketing-definitions.d.ts.map +1 -0
  107. package/dist/mcp/tools/marketing-definitions.js +37 -0
  108. package/dist/mcp/tools/marketing-definitions.js.map +1 -0
  109. package/dist/mcp/tools/marketing-report.d.ts +7 -0
  110. package/dist/mcp/tools/marketing-report.d.ts.map +1 -1
  111. package/dist/mcp/tools/marketing-report.js +43 -5
  112. package/dist/mcp/tools/marketing-report.js.map +1 -1
  113. package/dist/mcp/tools/posts.d.ts.map +1 -1
  114. package/dist/mcp/tools/posts.js +16 -0
  115. package/dist/mcp/tools/posts.js.map +1 -1
  116. package/dist/mcp/tools/promises.d.ts +39 -0
  117. package/dist/mcp/tools/promises.d.ts.map +1 -0
  118. package/dist/mcp/tools/promises.js +98 -0
  119. package/dist/mcp/tools/promises.js.map +1 -0
  120. package/dist/mcp/tools/proposals.d.ts +26 -0
  121. package/dist/mcp/tools/proposals.d.ts.map +1 -0
  122. package/dist/mcp/tools/proposals.js +102 -0
  123. package/dist/mcp/tools/proposals.js.map +1 -0
  124. package/dist/mcp/tools/safe-zone-pixels.d.ts +165 -0
  125. package/dist/mcp/tools/safe-zone-pixels.d.ts.map +1 -0
  126. package/dist/mcp/tools/safe-zone-pixels.js +300 -0
  127. package/dist/mcp/tools/safe-zone-pixels.js.map +1 -0
  128. package/dist/mcp/tools/slideshow-render.d.ts.map +1 -1
  129. package/dist/mcp/tools/slideshow-render.js +3 -1
  130. package/dist/mcp/tools/slideshow-render.js.map +1 -1
  131. package/dist/mcp/tools/switchback.d.ts +36 -0
  132. package/dist/mcp/tools/switchback.d.ts.map +1 -0
  133. package/dist/mcp/tools/switchback.js +123 -0
  134. package/dist/mcp/tools/switchback.js.map +1 -0
  135. package/dist/mcp/tools/verification.d.ts +24 -0
  136. package/dist/mcp/tools/verification.d.ts.map +1 -0
  137. package/dist/mcp/tools/verification.js +124 -0
  138. package/dist/mcp/tools/verification.js.map +1 -0
  139. package/package.json +4 -2
package/dist/mcp/index.js CHANGED
@@ -17,9 +17,21 @@ import { submitKnowledgeSource, readKnowledgeSources, searchKnowledge, readKnowl
17
17
  import { listPublishTargets, setPublishTargets, uploadAsset, retryFailedPublishTargets, completeManualPublish, requestTikTokConsent, } from './tools/marketing.js';
18
18
  import { createPost, getPostStatus, submitPost, listPosts, submitReview, listAssets, getPostAnalytics, listTopPosts, } from './tools/posts.js';
19
19
  import { getMarketingInsights } from './tools/insights.js';
20
+ import { getBudgetPacing, setMarketingBudget, setStopRule, removeStopRule } from './tools/budget.js';
21
+ import { getMarketingDefinitions } from './tools/marketing-definitions.js';
20
22
  import { getMarketingReport, setMarketingBenchmark, deleteMarketingBenchmark } from './tools/marketing-report.js';
23
+ import { getVerificationLedger, recordPlatformRead } from './tools/verification.js';
24
+ import { proposeMarketingChange, installWeeklyGrowthWorkflow } from './tools/proposals.js';
25
+ import { getGrowthSignals, setMarketingMoment, linkMomentChange, addCompetitor, removeCompetitor, setTrackedKeywords, } from './tools/growth-signals.js';
26
+ import { getAiVisibility, setAiQuestions, runAiVisibilityCheck } from './tools/ai-visibility.js';
27
+ import { createSwitchbackTest, startSwitchbackTest, getSwitchbackTest, listSwitchbackTests } from './tools/switchback.js';
28
+ import { importMarketingChanges } from './tools/marketing-changes.js';
29
+ import { getCreatorResults } from './tools/creators.js';
30
+ import { createTrackedLink, listTrackedLinks } from './tools/links.js';
31
+ import { tagMessage, untagMessage, listPromises } from './tools/promises.js';
21
32
  import { getBrandKit, updateBrandKit, createBrandKit, uploadBrandImage, listCreatives, listCreativeMedia, getCreative, createCreative, updateCreative, uploadCreativeMediaAny, uploadCreativePhoto, renderCreativeTool, previewCreative, attachCreativeToPost, createExperiment, } from './tools/creatives.js';
22
33
  import { previewCreativeDraft, commitCreativeDraft, } from './tools/creative-drafts.js';
34
+ import { closeOcr } from '../lib/safe-zone/ocr.js';
23
35
  import { resolveCreativeId } from '../lib/creative-id.js';
24
36
  import { deleteMedia, deleteCreative } from './tools/creative-delete.js';
25
37
  const CREATIVE_TOOLS = [
@@ -85,7 +97,7 @@ const CREATIVE_FIELD_PROPERTIES = {
85
97
  slideAltText: {
86
98
  type: 'array',
87
99
  items: { type: 'string' },
88
- description: 'CAROUSEL only: alt text per slide, index-aligned (entry N describes slide N in every placement).',
100
+ description: 'CAROUSEL only: alt text per slide, index-aligned (entry N describes slide N in every placement). Convention: describe the picture, then `Text: "line one" / "line two"` for the words printed on the slide (or `Text: none`). That Text part times the slides of a slideshow video.',
89
101
  },
90
102
  motion: {
91
103
  type: 'object',
@@ -121,7 +133,7 @@ const CREATIVE_FIELD_PROPERTIES = {
121
133
  },
122
134
  slideshow: {
123
135
  type: 'object',
124
- description: 'CAROUSEL only: how the 9x16 slides become a video when audio.source is track. slideDurations: seconds per 9x16 slide, one entry per slide, each 1-10 (default 3 for the first, 2.5 for the rest). zoom: slow push-in on each slide, default true. Slides cross-fade for 0.5 s.',
136
+ description: 'CAROUSEL only: how the 9x16 slides become a video when audio.source is track. slideDurations: seconds per 9x16 slide, one entry per slide, each 1-10. Omitted: the tool times each slide from its text (clamp(2.4 + 0.14 x words, 3.0, 4.8) s, +0.5 s on the first slide, +0.5 s on an app screen or chart), and 3.5 s first / 3.0 s rest when there is no text. zoom: slow push-in on each slide, default true. Slides cross-fade for 0.5 s, out of each slide\'s time.',
125
137
  properties: {
126
138
  slideDurations: { type: 'array', items: { type: 'number' } },
127
139
  zoom: { type: 'boolean' },
@@ -1281,19 +1293,79 @@ export const TOOLS = [
1281
1293
  },
1282
1294
  },
1283
1295
  },
1296
+ {
1297
+ name: 'get_budget_pacing',
1298
+ description: 'Paid spend against the month\'s budget cap, per paid channel (any channel with a spend metric; Apple Ads is one). Returns the cap (null when none is set: then there is no pace), settled month-to-date spend (provisionalSpend is kept apart and never counted), pacePct against a straight-line expectation (1.0 = on pace), projected month-end spend, the last 7 days, and per channel: compliance (spend with no active stop rule is non-compliant), each stop rule with its observed value and state (TRIPPED, BELOW_MIN_SAMPLE, NO_DATA, OK), and marginal cost per install (last 7 settled days vs the prior 7 vs month-to-date; cpiNote "no installs" when a window has none). Read-only. Conductor only proposes and records: a tripped rule is a prompt for a human to change the bid or budget in the ad platform (or Rexipe\'s gated tool). Set the cap with set_marketing_budget and rules with set_stop_rule.',
1299
+ inputSchema: {
1300
+ type: 'object',
1301
+ properties: {
1302
+ month: { type: 'string', description: 'YYYY-MM, UTC (default: the current month)' },
1303
+ },
1304
+ },
1305
+ },
1306
+ {
1307
+ name: 'set_marketing_budget',
1308
+ description: 'Set or replace the paid budget cap for a month (idempotent per month). capAmount must be above 0; to have no cap, set none. Spend is summed as the ad platform reports it, so give the cap in that account\'s currency. Records the cap only; it does not change any ad platform. Requires the Editor role (or Admin). Verify with get_budget_pacing.',
1309
+ inputSchema: {
1310
+ type: 'object',
1311
+ properties: {
1312
+ month: { type: 'string', description: 'YYYY-MM, UTC' },
1313
+ capAmount: { type: 'number', description: 'The month\'s cap, above 0' },
1314
+ currency: { type: 'string', description: 'Three-letter code (default USD)' },
1315
+ },
1316
+ required: ['month', 'capAmount'],
1317
+ },
1318
+ },
1319
+ {
1320
+ name: 'set_stop_rule',
1321
+ description: 'Add a stop rule for a paid channel: it trips when `metric` is above (GT) or below (LT) `threshold` over the last `windowDays` settled days, once the window holds at least `minSample` taps. A rule below its minSample never trips, so set one for any rate or cost per install. A paid channel with spend needs at least one active rule or get_budget_pacing flags it non-compliant. Rates are fractions (0.05 = 5%). scope narrows it to one campaign or keyword by id. Conductor only evaluates and records: a tripped rule is a prompt for a human to change the bid or budget in the ad platform (or Rexipe\'s gated tool), never an action taken here. Requires the Editor role (or Admin). Verify with get_budget_pacing; remove with remove_stop_rule.',
1322
+ inputSchema: {
1323
+ type: 'object',
1324
+ properties: {
1325
+ channel: { type: 'string', description: 'The channel, e.g. ADS' },
1326
+ metric: { type: 'string', enum: ['cost_per_install', 'spend', 'installs', 'taps', 'tap_through_rate', 'install_rate'], description: 'What to watch. tap_through_rate = taps / impressions; install_rate = installs / taps' },
1327
+ comparator: { type: 'string', enum: ['GT', 'LT'], description: 'GT trips above the threshold, LT below' },
1328
+ threshold: { type: 'number', description: 'In the metric\'s own unit, 0 or more' },
1329
+ minSample: { type: 'number', description: 'Taps the window must hold before the rule can trip (default 0 = none)' },
1330
+ windowDays: { type: 'number', description: 'Settled days to read, 1 to 90 (default 7)' },
1331
+ scope: { type: 'string', description: 'channel (default), campaign:<id> or keyword:<id>' },
1332
+ note: { type: 'string', description: 'What a human should consider when it trips (optional)' },
1333
+ },
1334
+ required: ['channel', 'metric', 'comparator', 'threshold'],
1335
+ },
1336
+ },
1337
+ {
1338
+ name: 'remove_stop_rule',
1339
+ description: 'Remove a stop rule by id (it stays on record but stops being evaluated). Removing the last active rule of a paid channel makes it non-compliant again. Requires the Editor role (or Admin). Find ruleId in get_budget_pacing (channels[].rules); verify there afterwards.',
1340
+ inputSchema: {
1341
+ type: 'object',
1342
+ properties: { ruleId: { type: 'string', description: 'The rule id from get_budget_pacing or set_stop_rule' } },
1343
+ required: ['ruleId'],
1344
+ },
1345
+ },
1346
+ {
1347
+ name: 'get_marketing_definitions',
1348
+ description: 'What each marketing metric counts: per metric (metricRef CHANNEL.key) its source report or field, numerator and denominator, source type (ALL or one App Store traffic source), what it excludes and the time zone of its days. Check it before comparing a metric with a benchmark or another source: two figures compare only when numerator, denominator and source type match. Read-only. Use get_marketing_report or get_marketing_insights for the numbers.',
1349
+ inputSchema: {
1350
+ type: 'object',
1351
+ properties: {
1352
+ channel: { type: 'string', enum: ['WEB', 'SEARCH', 'SOCIAL', 'ADS', 'STORE', 'PRODUCT'], description: 'Only this channel\'s metrics (default all)' },
1353
+ },
1354
+ },
1355
+ },
1284
1356
  {
1285
1357
  name: 'get_marketing_report',
1286
- description: 'The whole-funnel marketing report in one payload: sources, headline, acquisition, funnel, scorecard, keywords, ads, benchmarks and changes. Percent values are fractions. Read-only. Use get_marketing_insights for per-Post performance; set_marketing_benchmark to record an industry benchmark.',
1358
+ description: 'The whole-funnel marketing report in one payload: sources, headline, acquisition (organic search net of Apple Ads over the same settled days, see derivation), funnel, store downloads of record, scorecard, keywords (with cost per activated install, week-2 retained install and trial), payback (cohort proceeds over spend per paid channel, 12-month horizon), exclusions (likely App Review installs), asoKeywords (organic rank and popularity, best 20), email, shares and link_family acquisition rows, a verification tally, adsCoverage, ads, benchmarks (judged only against a metric with the same definition), changes with changeMarkers, and definitions for every metric. A figure the source did not send is absent or null, never 0. Percent values are fractions. Read-only. Use get_marketing_insights for per-Post performance; set_marketing_benchmark to record an industry benchmark.',
1287
1359
  inputSchema: {
1288
1360
  type: 'object',
1289
1361
  properties: {
1290
- window: { type: 'string', enum: ['7d', '28d'], description: 'Report window (default 28d)' },
1362
+ window: { type: 'string', description: 'Report window: "7d", "28d" (default) or a fixed range "YYYY-MM-DD..YYYY-MM-DD" (at most 92 days, ending yesterday or earlier), e.g. to check a past window against platform numbers' },
1291
1363
  },
1292
1364
  },
1293
1365
  },
1294
1366
  {
1295
1367
  name: 'set_marketing_benchmark',
1296
- description: 'Record or replace the industry benchmark for one metric. The value must come from a source you read in this session, never from memory: sourceUrl (the page) and checkedOn (the day you read it) are required. metricRef is CHANNEL.metric (e.g. STORE.conversion_rate) or PRODUCT.<key>. A count or currency total (downloads, spend) is stated per 28 days and prorated to the report window; a rate or ratio is compared as stated. Requires the Editor role (or Admin). Verify with get_marketing_report (benchmarks).',
1368
+ description: 'Record or replace the industry benchmark for one metric. The value must come from a source you read in this session, never from memory: sourceUrl (the page) and checkedOn (the day you read it) are required. metricRef is CHANNEL.metric (e.g. STORE.conversion_rate) or PRODUCT.<key>. A count or currency total (downloads, spend) is stated per 28 days and prorated to the report window; a rate or ratio is compared as stated. Say what it measures with numerator, denominator and sourceType: a benchmark is judged only against a metric with the same definition, and one without them shows as "definition missing". Each call replaces the whole benchmark, so repeat the definition when you update the value. Requires the Editor role (or Admin). Verify with get_marketing_report (benchmarks).',
1297
1369
  inputSchema: {
1298
1370
  type: 'object',
1299
1371
  properties: {
@@ -1306,6 +1378,9 @@ export const TOOLS = [
1306
1378
  sourceUrl: { type: 'string', description: 'http(s) URL of the page you read' },
1307
1379
  checkedOn: { type: 'string', description: 'YYYY-MM-DD, the day you read the source (not in the future)' },
1308
1380
  notes: { type: 'string', description: 'Caveats (optional)' },
1381
+ numerator: { type: 'string', description: 'What the benchmark counts (optional): impressions, unique_impressions, page_views, unique_page_views, first_time_downloads, redownloads, total_downloads, downloads_of_record, tap_installs, tap_new_downloads, view_through_installs, taps, spend, visitors, sessions, pageviews, conversion_sessions, conversion_events, clicks, followers, posts, likes, channel_views, website_clicks, rating_count, rating_avg, position, or product:<key> for an in-app metric. AppFollow example: total_downloads' },
1382
+ denominator: { type: 'string', description: 'What the numerator is divided by (optional; same names as numerator; omit for a count; needs numerator). AppFollow example: unique_impressions' },
1383
+ sourceType: { type: 'string', description: 'The traffic source it covers (optional; needs numerator): ALL (default), APP_STORE_SEARCH, APP_STORE_BROWSE, APP_REFERRER, WEB_REFERRER, APP_CLIP, INSTITUTIONAL_PURCHASE or OTHER. AppFollow example: APP_STORE_SEARCH' },
1309
1384
  },
1310
1385
  required: ['metricRef', 'value', 'sourceName', 'sourceUrl', 'checkedOn'],
1311
1386
  },
@@ -1319,6 +1394,318 @@ export const TOOLS = [
1319
1394
  required: ['metricRef'],
1320
1395
  },
1321
1396
  },
1397
+ {
1398
+ name: 'get_verification_ledger',
1399
+ description: 'Which marketing numbers to trust: per metric (CHANNEL.key) Conductor\'s value, the product backend\'s value over the settled days both have, the latest direct platform read and a verdict. BOTH: every second source agrees. CONNECTOR: trust the connector (a read agrees with it, or only the backend disagrees). BACKEND: backend and read agree, the connector does not. PLATFORM: the read disagrees with every other source. UNCHECKED: no second source, never verified. `mismatch` means a second source disagrees; `stale` means the read is over 7 days old; `over` is set when a row covers other days than the window. Cite a number only when its verdict is not UNCHECKED and it has no mismatch. Read-only. Use record_platform_read to log a direct read.',
1400
+ inputSchema: {
1401
+ type: 'object',
1402
+ properties: {
1403
+ window: { type: 'string', description: '7d, 28d (default), 90d, or a range of whole days YYYY-MM-DD..YYYY-MM-DD ending yesterday or earlier (at most 92 days)' },
1404
+ channel: { type: 'string', enum: ['WEB', 'SEARCH', 'SOCIAL', 'ADS', 'STORE', 'PRODUCT'], description: 'Only this channel\'s rows (default all)' },
1405
+ onlyProblems: { type: 'boolean', description: 'Only rows that are UNCHECKED, have a mismatch or have a stale read (default false)' },
1406
+ },
1407
+ },
1408
+ },
1409
+ {
1410
+ name: 'record_platform_read',
1411
+ description: 'Log a direct read: what the platform\'s own UI or API shows for one metric over an exact day range. Look at the platform for that range; never copy Conductor\'s number. from and to are whole days, to yesterday or earlier, at most 92 days apart (a level such as followers is read on `to`; unique visitors need a range of 7, 28 or 90 days). Append-only: a newer read supersedes this one, nothing is edited or deleted. Returns the metric\'s row with its verdict. Requires the Editor role (or Admin). Always call get_verification_ledger after to verify.',
1412
+ inputSchema: {
1413
+ type: 'object',
1414
+ properties: {
1415
+ channel: { type: 'string', enum: ['WEB', 'SEARCH', 'SOCIAL', 'ADS', 'STORE', 'PRODUCT'], description: 'The channel the metric belongs to' },
1416
+ metric: { type: 'string', description: 'Metric key within the channel, e.g. installs (ADS), clicks (SEARCH), downloads (STORE); a sum, a level or visitors, not a ratio' },
1417
+ from: { type: 'string', description: 'First day the platform figure covers, YYYY-MM-DD' },
1418
+ to: { type: 'string', description: 'Last day the platform figure covers, YYYY-MM-DD (yesterday or earlier)' },
1419
+ value: { type: 'number', description: 'The platform\'s figure for those days (zero or more)' },
1420
+ sourceName: { type: 'string', description: 'Where you read it, e.g. Apple Ads console or Search Console UI' },
1421
+ note: { type: 'string', description: 'Caveats, e.g. the filter or time zone the platform used (optional)' },
1422
+ },
1423
+ required: ['channel', 'metric', 'from', 'to', 'value', 'sourceName'],
1424
+ },
1425
+ },
1426
+ {
1427
+ name: 'propose_marketing_change',
1428
+ description: 'Propose one marketing change, backed by exactly two signals on two different metrics, as a PLANNED change with a review date. It refuses a signal whose metric get_verification_ledger does not verify (UNCHECKED, a MISMATCH or no row; it names the metric and verdict), a value that is not the ledger\'s figure for that window, and more than 3 a week per workspace (ISO week, UTC). A human approves every change: it stays PLANNED and moving it to LIVE is a human step this tool cannot take. It changes nothing on an ad platform. Requires the Editor role (or Admin). Verify with get_work_item (workItemId) or get_marketing_report (changes).',
1429
+ inputSchema: {
1430
+ type: 'object',
1431
+ properties: {
1432
+ title: { type: 'string', description: 'Short name of the change (at most 255 characters)' },
1433
+ type: { type: 'string', description: 'A type of the workspace\'s MARKETING_CHANGES workflow (LISTING, ADS, PRICING, PRODUCT, CONTENT, BASELINE or OTHER by default)' },
1434
+ hypothesis: { type: 'string', description: 'What to change and what you expect it to do' },
1435
+ reviewOn: { type: 'string', description: 'YYYY-MM-DD, the day to review the result; after today' },
1436
+ signals: {
1437
+ type: 'array',
1438
+ minItems: 2,
1439
+ maxItems: 2,
1440
+ description: 'The evidence: two figures on two different metrics, each verified by the ledger for its window',
1441
+ items: {
1442
+ type: 'object',
1443
+ properties: {
1444
+ metricRef: { type: 'string', description: 'CHANNEL.metric as in get_verification_ledger, e.g. ADS.installs' },
1445
+ window: { type: 'string', description: '7d, 28d, 90d or YYYY-MM-DD..YYYY-MM-DD: the window the figure is for' },
1446
+ value: { type: 'number', description: 'The ledger\'s figure for that metric over that window' },
1447
+ note: { type: 'string', description: 'What the figure shows (optional)' },
1448
+ },
1449
+ required: ['metricRef', 'window', 'value'],
1450
+ },
1451
+ },
1452
+ runId: { type: 'string', description: 'The workflow run making the proposal (optional)' },
1453
+ },
1454
+ required: ['title', 'type', 'hypothesis', 'reviewOn', 'signals'],
1455
+ },
1456
+ },
1457
+ {
1458
+ name: 'install_weekly_growth_workflow',
1459
+ description: 'Install the "Weekly growth review" workflow from Conductor\'s template: every Monday 07:30 UTC a Claude Code step reads the report, the verification ledger and the budget, and proposes at most 3 changes with propose_marketing_change. It is created disabled, so nothing runs until a person enables it, and its Claude Code step needs a runtime target. Safe to repeat: an existing workflow with that name is returned unchanged. Requires the Admin role. Verify with get_workflow (workflowId).',
1460
+ inputSchema: { type: 'object', properties: {} },
1461
+ },
1462
+ {
1463
+ name: 'get_growth_signals',
1464
+ description: 'Growth signals from public data: seasonal moments with their surfaces and overdue warnings, the weekly ratings program (our app and each competitor: latest and previous snapshot, weeklyGrowth = rating-count change, null until two snapshots), recent reviews, what changed on competitor listings, and App Store keyword positions. Read-only. Change the inputs with set_marketing_moment, link_moment_change, add_competitor, remove_competitor and set_tracked_keywords.',
1465
+ inputSchema: { type: 'object', properties: {} },
1466
+ },
1467
+ {
1468
+ name: 'set_marketing_moment',
1469
+ description: 'Record or replace a dated moment (for example Thanksgiving, 2026-11-26) and the surfaces that must change for it, each with a due date. A surface past its due date with no linked change shows a warning. surfaces is the whole list: a surface kept by name keeps its linked change, one left out is removed. Requires the Editor role (or Admin). Verify with get_growth_signals (moments).',
1470
+ inputSchema: {
1471
+ type: 'object',
1472
+ properties: {
1473
+ key: { type: 'string', description: 'Stable id: lower-case letters, digits, hyphens, underscores (e.g. thanksgiving-2026)' },
1474
+ name: { type: 'string', description: 'Display name' },
1475
+ date: { type: 'string', description: 'YYYY-MM-DD, the day of the moment' },
1476
+ leadDays: { type: 'integer', description: 'Days ahead the moment counts as upcoming (default 21)' },
1477
+ surfaces: {
1478
+ type: 'array',
1479
+ description: 'Where a change is needed and by when',
1480
+ items: {
1481
+ type: 'object',
1482
+ properties: {
1483
+ surface: { type: 'string', description: 'e.g. App Store promotional text, TikTok post, Email' },
1484
+ dueOn: { type: 'string', description: 'YYYY-MM-DD, the day the change must be recorded by' },
1485
+ },
1486
+ required: ['surface', 'dueOn'],
1487
+ },
1488
+ },
1489
+ },
1490
+ required: ['key', 'name', 'date', 'surfaces'],
1491
+ },
1492
+ },
1493
+ {
1494
+ name: 'link_moment_change',
1495
+ description: 'Record the marketing change (a MARKETING_CHANGES Work Item of this project) that handled a moment surface, which clears its warning. A Work Item of another project or workflow is refused. Requires the Editor role (or Admin). Verify with get_growth_signals (moments).',
1496
+ inputSchema: {
1497
+ type: 'object',
1498
+ properties: {
1499
+ key: { type: 'string', description: 'The moment key' },
1500
+ surfaceId: { type: 'string', description: 'The surface id from get_growth_signals' },
1501
+ workItemId: { type: 'string', description: 'The change Work Item: its id or display id (e.g. RE-12)' },
1502
+ },
1503
+ required: ['key', 'surfaceId', 'workItemId'],
1504
+ },
1505
+ },
1506
+ {
1507
+ name: 'add_competitor',
1508
+ description: 'Watch a competitor app: each week its public App Store listing, rating count, reviews and keyword positions are recorded. Idempotent per appId (re-adding updates the name and country). Requires the Editor role (or Admin). Verify with get_growth_signals (ratings.competitors); data appears after the next weekly run.',
1509
+ inputSchema: {
1510
+ type: 'object',
1511
+ properties: {
1512
+ appId: { type: 'string', description: 'Numeric App Store id, digits only' },
1513
+ name: { type: 'string', description: 'Display name' },
1514
+ country: { type: 'string', description: 'Two-letter App Store country (default: our app\'s)' },
1515
+ },
1516
+ required: ['appId', 'name'],
1517
+ },
1518
+ },
1519
+ {
1520
+ name: 'remove_competitor',
1521
+ description: 'Stop watching a competitor app (idempotent); its stored history is kept. Requires the Editor role (or Admin). Verify with get_growth_signals (ratings.competitors).',
1522
+ inputSchema: {
1523
+ type: 'object',
1524
+ properties: { appId: { type: 'string', description: 'Numeric App Store id' } },
1525
+ required: ['appId'],
1526
+ },
1527
+ },
1528
+ {
1529
+ name: 'set_tracked_keywords',
1530
+ description: 'Replace the App Store keywords whose search position is recorded weekly for our app and each competitor (at most 25; an empty list clears it). Used only while the product feed has no aso:<keyword> rows; otherwise those keywords are tracked. Requires the Editor role (or Admin). Verify with get_growth_signals (trackedKeywords, keywordPresence).',
1531
+ inputSchema: {
1532
+ type: 'object',
1533
+ properties: {
1534
+ keywords: { type: 'array', items: { type: 'string' }, description: 'The full list of keywords' },
1535
+ country: { type: 'string', description: 'Two-letter App Store country to search in (default: our app\'s)' },
1536
+ },
1537
+ required: ['keywords'],
1538
+ },
1539
+ },
1540
+ {
1541
+ name: 'get_ai_visibility',
1542
+ description: 'Whether AI assistants name the brand when asked a fixed set of questions, checked weekly: per question and assistant the latest answer (named or not, list rank, excerpt) and a weekly trend. An assistant the workspace has no provider key for is listed under skipped and has no readings; it is never shown as not named. Read-only. Change the questions with set_ai_questions.',
1543
+ inputSchema: {
1544
+ type: 'object',
1545
+ properties: {
1546
+ weeks: { type: 'integer', description: 'ISO weeks back to read, 1-52 (default 8)' },
1547
+ },
1548
+ },
1549
+ },
1550
+ {
1551
+ name: 'set_ai_questions',
1552
+ description: 'Replace the questions put to the AI assistants each week (at most 20; an empty list switches all off; dropped questions keep their history), and optionally the brand terms that count as naming the brand (default: the workspace name; an empty list goes back to it). Requires the Editor role (or Admin). Verify with get_ai_visibility.',
1553
+ inputSchema: {
1554
+ type: 'object',
1555
+ properties: {
1556
+ questions: { type: 'array', items: { type: 'string' }, description: 'The full list of questions, e.g. "best app to save recipes from TikTok"' },
1557
+ brandTerms: { type: 'array', items: { type: 'string' }, description: 'Words that count as naming the brand, whole word in any case with an optional plural s (omit to leave unchanged)' },
1558
+ },
1559
+ required: ['questions'],
1560
+ },
1561
+ },
1562
+ {
1563
+ name: 'run_ai_visibility_check',
1564
+ description: 'Run this week\'s AI-assistant checks now instead of waiting for Monday. Spends the workspace\'s own AI provider keys (at most 20 calls a week) and needs the Admin role. Safe to repeat: a question and assistant already read this week is not asked again. Returns what was recorded, skipped (no credential, weekly limit) and failed. Call get_ai_visibility after to read the results.',
1565
+ inputSchema: { type: 'object', properties: {} },
1566
+ },
1567
+ {
1568
+ name: 'create_switchback_test',
1569
+ description: 'Declare a weekly on/off test of one Apple Ads keyword to see whether paid adds installs or only relabels organic ones. Give weeks, or startWeek (a Monday) with weekCount (2-12, alternating, first week ON). The rule and minimum n are fixed up front (defaults: total installs up by at least 1 a week, organic down by at most 20%, 20 search downloads). Creates a draft; call start_switchback_test to freeze it. A person switches the keyword in the ad platform or through Rexipe\'s gated tool; Conductor never does. Requires the Editor role (or Admin). Verify with get_switchback_test.',
1570
+ inputSchema: {
1571
+ type: 'object',
1572
+ properties: {
1573
+ name: { type: 'string', description: 'A label for the test' },
1574
+ keywordId: { type: 'string', description: 'The Apple Ads keyword id' },
1575
+ keywordText: { type: 'string', description: 'The keyword text' },
1576
+ weeks: {
1577
+ type: 'array',
1578
+ items: {
1579
+ type: 'object',
1580
+ properties: {
1581
+ weekStart: { type: 'string', description: 'A Monday, yyyy-MM-dd (UTC)' },
1582
+ on: { type: 'boolean', description: 'true = keyword on that week, false = off' },
1583
+ },
1584
+ required: ['weekStart', 'on'],
1585
+ },
1586
+ description: 'Consecutive Mondays with at least one on and one off week (omit when using startWeek and weekCount)',
1587
+ },
1588
+ startWeek: { type: 'string', description: 'First Monday, yyyy-MM-dd; use with weekCount instead of weeks' },
1589
+ weekCount: { type: 'integer', description: 'How many weeks, 2-12; used with startWeek' },
1590
+ minN: { type: 'integer', description: 'Fewest first-time search downloads across all weeks a verdict may rest on (default 20)' },
1591
+ minLift: { type: 'number', description: 'Extra total first-time installs a week paid must add (default 1)' },
1592
+ maxCannibalisationPct: { type: 'number', description: 'Most the on-week organic mean may fall, in percent (default 20)' },
1593
+ },
1594
+ required: ['name', 'keywordId', 'keywordText'],
1595
+ },
1596
+ },
1597
+ {
1598
+ name: 'start_switchback_test',
1599
+ description: 'Start a drafted switchback test: from now its weeks and rule cannot change (edits are refused). The first week must not have begun. The test then settles itself once its last week has ended and the daily data is settled, recording the verdict as a reviewed change; no polling needed. Requires the Editor role (or Admin). Verify with get_switchback_test, which also says which state the keyword should be in this week.',
1600
+ inputSchema: {
1601
+ type: 'object',
1602
+ properties: { id: { type: 'string', description: 'The test id' } },
1603
+ required: ['id'],
1604
+ },
1605
+ },
1606
+ {
1607
+ name: 'get_switchback_test',
1608
+ description: 'One switchback test: its plan, the rule, which state (ON, OFF or not running) the keyword should be in this week, what it is waiting for when its last week has ended but data is not settled, and once settled the verdict, per-week figures, n reached and the change Work Item that records it. Read-only.',
1609
+ inputSchema: {
1610
+ type: 'object',
1611
+ properties: { id: { type: 'string', description: 'The test id' } },
1612
+ required: ['id'],
1613
+ },
1614
+ },
1615
+ {
1616
+ name: 'list_switchback_tests',
1617
+ description: 'The workspace\'s switchback tests, newest first, with status, this week\'s state and any verdict. Read-only. Read one with get_switchback_test.',
1618
+ inputSchema: { type: 'object', properties: {} },
1619
+ },
1620
+ {
1621
+ name: 'import_marketing_changes',
1622
+ description: 'Import a marketing change log from a local JSONL file (one record per line: id, date, type, title, status, changed, evidence[], hypothesis, baseline, control, live_since, review_on, outcome, verdict, lesson, stop_rules, stop_rules_note) as Changes on the MARKETING_CHANGES workflow, each in the status its record has. Reference records are skipped; an unknown status or verdict refuses that record and names it, never guessed. A bad line stops everything before anything is sent. Safe to run again: a record already imported (same source and id) is left alone. Requires the Editor role (or Admin). Verify with get_marketing_report (changes).',
1623
+ inputSchema: {
1624
+ type: 'object',
1625
+ properties: {
1626
+ filePath: { type: 'string', description: 'Absolute path to the .jsonl file on this machine' },
1627
+ source: { type: 'string', description: 'Names the log the records come from (default "rexipe"); a record id is unique within its source' },
1628
+ },
1629
+ required: ['filePath'],
1630
+ },
1631
+ },
1632
+ {
1633
+ name: 'get_creator_results',
1634
+ description: 'What one creator (a Work Item on the CREATORS workflow) has produced: its posts with views, the downloads of its campaign links, and the redemptions of its offer code over a window of settled days (default the 28 days ending yesterday). An unknown figure is null with a note (Apple omits links under its reporting threshold; the product backend may not send redemptions), never 0. Read-only. Fill in the creator\'s fields with update_work_item.',
1635
+ inputSchema: {
1636
+ type: 'object',
1637
+ properties: {
1638
+ creatorId: { type: 'string', description: 'The creator Work Item: its id or display id (e.g. RE-12)' },
1639
+ from: { type: 'string', description: 'First day, YYYY-MM-DD (default 27 days before to)' },
1640
+ to: { type: 'string', description: 'Last day, YYYY-MM-DD, yesterday or earlier (default yesterday); at most 92 days from from' },
1641
+ },
1642
+ required: ['creatorId'],
1643
+ },
1644
+ },
1645
+ {
1646
+ name: 'create_tracked_link',
1647
+ description: 'Create an App Store campaign link (pt/ct) for a bio, creator, email or any other place, and return its url. Every new Post already gets one automatically, so use this for the rest. token is the ct (lowercase letters, digits, dashes, at most 40); family groups tokens so their downloads add up past Apple\'s reporting threshold (about 5 per token). One kind per family. Needs an App Store Connect connection with its provider token set. Requires the Editor role (or Admin). Verify with list_tracked_links.',
1648
+ inputSchema: {
1649
+ type: 'object',
1650
+ properties: {
1651
+ kind: { type: 'string', enum: ['POST', 'BIO', 'CREATOR', 'EMAIL', 'OTHER'], description: 'What the link is for. POST needs workItemId' },
1652
+ family: { type: 'string', description: 'The group the token rolls up into, e.g. creators (lowercase letters, digits, dashes, at most 64)' },
1653
+ token: { type: 'string', description: 'The campaign token (ct)' },
1654
+ label: { type: 'string', description: 'What the link is for, at most 200 characters (optional)' },
1655
+ workItemId: { type: 'string', description: 'The Work Item it belongs to, e.g. the creator (optional; required for POST)' },
1656
+ },
1657
+ required: ['kind', 'family', 'token'],
1658
+ },
1659
+ },
1660
+ {
1661
+ name: 'list_tracked_links',
1662
+ description: 'List tracked App Store links, newest first, with their urls. withPerformance adds per family: tokens, first-time downloads over the last 28 settled days and, for Post links, views. A family Apple reported nothing for has downloads null and belowThreshold true ("below Apple\'s reporting threshold"), which is not 0. Read-only. Create more with create_tracked_link; a Post\'s own link is also in get_post_status.',
1663
+ inputSchema: {
1664
+ type: 'object',
1665
+ properties: {
1666
+ kind: { type: 'string', enum: ['POST', 'BIO', 'CREATOR', 'EMAIL', 'OTHER'], description: 'Only this kind (optional)' },
1667
+ workItemId: { type: 'string', description: 'Only the links of this Work Item (optional)' },
1668
+ withPerformance: { type: 'boolean', description: 'Add downloads and views per family (default false)' },
1669
+ },
1670
+ },
1671
+ },
1672
+ {
1673
+ name: 'tag_message',
1674
+ description: 'Tag a target with the message it makes (a short tag such as save-from-tiktok): an Apple Ads keyword, a custom product page, a Post, a creative or a paywall headline. list_promises then joins the message to installs, intent picks, trial rate and D7. A target carries one message: tagging it again moves it and replaces its label. targetRef is the keyword id, product page id, Post id or creative id, or the headline text for a paywall headline. Requires the Editor role (or Admin). Verify with list_promises.',
1675
+ inputSchema: {
1676
+ type: 'object',
1677
+ properties: {
1678
+ message: { type: 'string', description: 'The message, at most 120 characters (stored lower-case). Match the product feed\'s message:<tag> value to see outcomes' },
1679
+ targetKind: { type: 'string', enum: ['CREATIVE', 'PRODUCT_PAGE', 'KEYWORD', 'PAYWALL_HEADLINE', 'POST'], description: 'What is being tagged' },
1680
+ targetRef: { type: 'string', description: 'The target\'s id, or the headline text for PAYWALL_HEADLINE' },
1681
+ label: { type: 'string', description: 'A human name for the target, at most 200 characters (optional)' },
1682
+ },
1683
+ required: ['message', 'targetKind', 'targetRef'],
1684
+ },
1685
+ },
1686
+ {
1687
+ name: 'untag_message',
1688
+ description: 'Remove the message from a target. Safe to repeat: untagging a target with no tag changes nothing. Requires the Editor role (or Admin). Verify with list_promises.',
1689
+ inputSchema: {
1690
+ type: 'object',
1691
+ properties: {
1692
+ targetKind: { type: 'string', enum: ['CREATIVE', 'PRODUCT_PAGE', 'KEYWORD', 'PAYWALL_HEADLINE', 'POST'], description: 'What was tagged' },
1693
+ targetRef: { type: 'string', description: 'The id (or headline text) the tag was made with' },
1694
+ },
1695
+ required: ['targetKind', 'targetRef'],
1696
+ },
1697
+ },
1698
+ {
1699
+ name: 'list_promises',
1700
+ description: 'The promise ledger: per message, the tagged targets by kind, installs (Apple Ads tap installs of tagged keywords and product pages plus first-time downloads of tagged Posts\' links), intent mix, trial rate and D7, each rate with its 95% range and n, flagged "small sample" under n=20. A figure with no data is null, never 0. Default window: the last 28 settled days. Read-only. Tag targets with tag_message.',
1701
+ inputSchema: {
1702
+ type: 'object',
1703
+ properties: {
1704
+ from: { type: 'string', description: 'First day, YYYY-MM-DD (default 27 days before to)' },
1705
+ to: { type: 'string', description: 'Last day, YYYY-MM-DD (default the latest settled day)' },
1706
+ },
1707
+ },
1708
+ },
1322
1709
  {
1323
1710
  name: 'submit_review',
1324
1711
  description: 'Record a review verdict on a Post as this API key\'s user, who must be an assigned member holding the Reviewer role (or an Admin). Approving on a reviewed Workflow schedules it in the same call. TikTok consent is a human step the person does in their own browser (request_tiktok_consent hands them the link), not this tool. Returns the confirmation table.',
@@ -1614,7 +2001,7 @@ export const TOOLS = [
1614
2001
  },
1615
2002
  {
1616
2003
  name: 'render_creative',
1617
- description: 'Render a Creative to upload-ready frames — one JPEG per placement for STILL (Playwright on this machine), or one MP4 with a poster per placement for MOTION (ffmpeg-encoded on this machine) — or a small contact sheet with previewOnly. Runs synchronously: a STILL placement takes seconds; a MOTION placement takes roughly 20s per 8s of video, so a multi-placement MOTION render can take a couple of minutes. CLIP and CAROUSEL render on the server in one call (previewOnly is refused), unless the Creative has audio that needs encoding: a CAROUSEL with a track (adds one 9x16 slideshow MP4) or a CLIP with track, mix or none (re-muxed on this machine, with ffmpeg). Returns the render id, state, frame URLs (MOTION frames also carry durationSeconds/hasAudio/posterUrl) and any warnings. Call preview_creative to actually look at the result.',
2004
+ description: 'Render a Creative to upload-ready frames — one JPEG per placement for STILL (Playwright on this machine), or one MP4 with a poster per placement for MOTION (ffmpeg-encoded on this machine) — or a small contact sheet with previewOnly. Runs synchronously: a STILL placement takes seconds; a MOTION placement takes roughly 20s per 8s of video, so a multi-placement MOTION render can take a couple of minutes. CLIP and CAROUSEL render on the server in one call (previewOnly is refused), unless the Creative has audio that needs encoding: a CAROUSEL with a track (adds one 9x16 slideshow MP4) or a CLIP with track, mix or none (re-muxed on this machine, with ffmpeg). Returns the render id, state, frame URLs (MOTION frames also carry durationSeconds/hasAudio/posterUrl) and any warnings. For a CAROUSEL or CLIP with a 9x16 placement it also reports checks for text under the platform UI (reported only, never blocking). Call preview_creative to actually look at the result.',
1618
2005
  inputSchema: {
1619
2006
  type: 'object',
1620
2007
  properties: {
@@ -1628,11 +2015,12 @@ export const TOOLS = [
1628
2015
  },
1629
2016
  {
1630
2017
  name: 'preview_creative',
1631
- description: "Look at a Creative: returns its latest contact sheet as an image (rendering a fresh previewOnly one first if none exists yet). For MOTION this is three key moments across the animation, not the finished video, with a text note giving the duration and — once a full render of the current version exists — its rendered MP4 URLs. Use this to judge the actual artwork — does the headline read at a glance, is the copy sitting on the subject's face — not just the data. If the image is too large to inline it returns the URL instead, with a note saying so.",
2018
+ description: "Look at a Creative: returns its latest contact sheet as an image (rendering a fresh previewOnly one first if none exists yet). For MOTION this is three key moments across the animation, not the finished video, with a text note giving the duration and — once a full render of the current version exists — its rendered MP4 URLs. Use this to judge the actual artwork — does the headline read at a glance, is the copy sitting on the subject's face — not just the data. If the image is too large to inline it returns the URL instead, with a note saying so. For a saved CAROUSEL or CLIP with a 9x16 placement it also downloads the 9x16 slides or video, checks them for text under the platform UI (checks, passed) and writes the Instagram/TikTok UI overlay sheets to disk (overlaySheets).",
1632
2019
  inputSchema: {
1633
2020
  type: 'object',
1634
2021
  properties: {
1635
2022
  creativeId: { type: 'string', description: 'Creative id, or its display id such as 12a' },
2023
+ uiOverlay: { type: 'string', enum: ['instagram', 'tiktok', 'both', 'none'], description: 'Which platform UI sheets to write for a CAROUSEL or CLIP (default both).' },
1636
2024
  },
1637
2025
  required: ['creativeId'],
1638
2026
  },
@@ -1693,7 +2081,7 @@ export const TOOLS = [
1693
2081
  },
1694
2082
  {
1695
2083
  name: 'preview_creative_draft',
1696
- description: "Look at a Creative BEFORE anything is saved: renders a draft on this machine and returns the contact sheet as an image plus the draftDir, readiness gaps and warnings. Takes the create_creative fields, plus local files (photoPath, clipPath, audioPath, per-beat photoPath) that are used for the render only. It never writes to Conductor — no Creative, no upload. It also runs the full render's per-placement checks (text spill, platform safe zones such as TikTok/Reels' overlay band, contrast, fonts, images) without saving anything and returns them as checks plus a passed flag. If passed is false, fix the design (copy, layout, layoutOverrides, typeOverrides) and call this again BEFORE showing the image or asking for approval — a failing check would fail the real render. Only when passed is true, show the image to the person; only after they approve, call commit_creative_draft. To change something, call this again. With baseCreativeId, previews edits on top of a saved Creative. For kind CAROUSEL pass slidePaths instead of a photo (the spec.json compose_slideshow wrote beside them is kept with the draft, or pass slideshowSpecPath): it returns one contact sheet per placement (slides in order), readiness and per-slide aspect violations; with a track (audio.trackId or audioPath) it also renders the slideshow MP4 on this machine and returns its path as slideshowVideoPath. Violations come back as a structured error and nothing is rendered.",
2084
+ description: "Look at a Creative BEFORE anything is saved: renders a draft on this machine and returns the contact sheet as an image plus the draftDir, readiness gaps and warnings. Takes the create_creative fields, plus local files (photoPath, clipPath, audioPath, per-beat photoPath) that are used for the render only. It never writes to Conductor — no Creative, no upload. It also runs the full render's per-placement checks (text spill, platform safe zones such as TikTok/Reels' overlay band, contrast, fonts, images) without saving anything and returns them as checks plus a passed flag. If passed is false, fix the design (copy, layout, layoutOverrides, typeOverrides) and call this again BEFORE showing the image or asking for approval — a failing check would fail the real render. Only when passed is true, show the image to the person; only after they approve, call commit_creative_draft. To change something, call this again. With baseCreativeId, previews edits on top of a saved Creative. For kind CAROUSEL pass slidePaths instead of a photo (the spec.json compose_slideshow wrote beside them is kept with the draft, or pass slideshowSpecPath): it returns one contact sheet per placement (slides in order), readiness and per-slide aspect violations; with a track (audio.trackId or audioPath) it also renders the slideshow MP4 on this machine and returns its path as slideshowVideoPath, timing each slide from its text when slideDurations is omitted (returns slideDurations, slideshowDurationSeconds and pacing; say the total length when showing it). Finished 9:16 slides (CAROUSEL) and videos (kind CLIP, via clipPath or clipPaths: nothing is sent to Conductor, no commit; then upload_creative_media + create_creative) are read for text under the platform UI: checks with rule safeZoneText (top y<290 is an error on slide 1 and in the first 3 s) or safeZoneUnchecked (could not look); passed false means fix the files and re-preview BEFORE showing them. The image shown for them is the Instagram UI drawn over the slides or the first seconds and each cut; overlaySheets lists the Instagram and TikTok sheets on disk (uiOverlay: instagram | tiktok | both (default) | none). Violations come back as a structured error and nothing is rendered.",
1697
2085
  inputSchema: {
1698
2086
  type: 'object',
1699
2087
  properties: {
@@ -1713,7 +2101,9 @@ export const TOOLS = [
1713
2101
  },
1714
2102
  },
1715
2103
  photoPath: { type: 'string', description: 'A photo on this machine (optional; use instead of photoId)' },
1716
- clipPath: { type: 'string', description: 'MOTION only: a video clip on this machine used as the background (optional; use instead of motion.background.clipMediaId)' },
2104
+ clipPath: { type: 'string', description: 'MOTION: a video clip on this machine used as the background (optional; use instead of motion.background.clipMediaId). kind CLIP: the finished video to check (9:16 unless its aspect says otherwise).' },
2105
+ clipPaths: { type: 'object', additionalProperties: { type: 'string' }, description: 'kind CLIP only: finished videos on this machine per placement, e.g. {"9x16": "/clips/a.mp4"}.' },
2106
+ uiOverlay: { type: 'string', enum: ['instagram', 'tiktok', 'both', 'none'], description: 'Platform UI drawn over 9:16 frames (default both, written to disk; the Instagram sheet is the image shown for a CAROUSEL or CLIP).' },
1717
2107
  audioPath: { type: 'string', description: 'MOTION or CAROUSEL: an audio file on this machine used as the music track (optional; use instead of audio.trackId). For a CAROUSEL, set audio.source to track too. Committing uploads it into the library — record its source and licence.' },
1718
2108
  slidePaths: {
1719
2109
  type: 'object',
@@ -1784,11 +2174,12 @@ export const TOOLS = [
1784
2174
  },
1785
2175
  {
1786
2176
  name: 'attach_creative_to_post',
1787
- description: "Attach a Creative's rendered frames to a Post as its media — placement to platform (9x16 to TikTok/Instagram Reels, 4x5 to Instagram feed, 1x1 to Facebook, story to story targets; sequence frames in order) — for every destination that has not set its own custom media. A CAROUSEL goes to Instagram feed (4x5), Facebook feed (1x1, else 4x5) and TikTok (9x16); Reels, Stories and YouTube cannot take its photos. A CAROUSEL with a track also has a slideshow video: per target, carouselAs (photos | video) in publish options picks which is sent (default video for TikTok and YouTube, photos for Instagram and Facebook feed). Uses the latest SUCCEEDED, non-preview render unless renderId is given (a CLIP or CAROUSEL with none is rendered first). A DRAFT Creative that passes readiness becomes READY on attach; the result's creativeState is its state afterwards and stateNote, when set, says why it stayed DRAFT. Call get_post_status (postId) to verify.",
2177
+ description: "Attach a Creative's rendered frames to a Post as its media — placement to platform (9x16 to TikTok/Instagram Reels, 4x5 to Instagram feed, 1x1 to Facebook, story to story targets; sequence frames in order) — for every destination that has not set its own custom media. A CAROUSEL goes to Instagram feed (4x5), Facebook feed (1x1, else 4x5) and TikTok (9x16); Reels, Stories and YouTube cannot take its photos. A CAROUSEL with a track also has a slideshow video: per target, carouselAs (photos | video) in publish options picks which is sent (default video for TikTok and YouTube, photos for Instagram and Facebook feed). Uses the latest SUCCEEDED, non-preview render unless renderId is given (a CLIP or CAROUSEL with none is rendered first). A DRAFT Creative that passes readiness becomes READY on attach; the result's creativeState is its state afterwards and stateNote, when set, says why it stayed DRAFT. Call get_post_status (postId) to verify. Pre-flight for a CAROUSEL or CLIP with a 9x16 placement: the rendered pixels are read for text under the platform UI, and an error (top y<290 on slide 1 or in the first 3 s) is refused with code SAFE_ZONE_TEXT and the checks; fix the media, or pass ignoreSafeZone: true only after the person accepts it. Warnings are returned as safeZoneChecks.",
1788
2178
  inputSchema: {
1789
2179
  type: 'object',
1790
2180
  properties: {
1791
2181
  creativeId: { type: 'string', description: 'Creative id, or its display id such as 12a' },
2182
+ ignoreSafeZone: { type: 'boolean', description: 'Attach despite a SAFE_ZONE_TEXT refusal. Only after the person has seen the checks and accepts them.' },
1792
2183
  postId: { type: 'string', description: "The Post's Work Item id — same value get_post_status takes as postId" },
1793
2184
  workItemId: { type: 'string', description: 'Deprecated alias for postId' },
1794
2185
  renderId: { type: 'string', description: 'A specific render to attach (optional — defaults to the latest SUCCEEDED render)' },
@@ -2418,6 +2809,34 @@ export async function runMcpServer() {
2418
2809
  channel: params['channel'],
2419
2810
  }));
2420
2811
  }
2812
+ case 'get_budget_pacing': {
2813
+ return successResponse(await getBudgetPacing(config, { month: params['month'] }));
2814
+ }
2815
+ case 'set_marketing_budget': {
2816
+ return successResponse(await setMarketingBudget(config, {
2817
+ month: params['month'],
2818
+ capAmount: params['capAmount'],
2819
+ currency: params['currency'],
2820
+ }));
2821
+ }
2822
+ case 'set_stop_rule': {
2823
+ return successResponse(await setStopRule(config, {
2824
+ channel: params['channel'],
2825
+ metric: params['metric'],
2826
+ comparator: params['comparator'],
2827
+ threshold: params['threshold'],
2828
+ minSample: params['minSample'],
2829
+ windowDays: params['windowDays'],
2830
+ scope: params['scope'],
2831
+ note: params['note'],
2832
+ }));
2833
+ }
2834
+ case 'remove_stop_rule': {
2835
+ return successResponse(await removeStopRule(config, { ruleId: params['ruleId'] }));
2836
+ }
2837
+ case 'get_marketing_definitions': {
2838
+ return successResponse(await getMarketingDefinitions(config, { channel: params['channel'] }));
2839
+ }
2421
2840
  case 'get_marketing_report': {
2422
2841
  return successResponse(await getMarketingReport(config, { window: params['window'] }));
2423
2842
  }
@@ -2432,11 +2851,163 @@ export async function runMcpServer() {
2432
2851
  sourceUrl: params['sourceUrl'],
2433
2852
  checkedOn: params['checkedOn'],
2434
2853
  notes: params['notes'],
2854
+ numerator: params['numerator'],
2855
+ denominator: params['denominator'],
2856
+ sourceType: params['sourceType'],
2435
2857
  }));
2436
2858
  }
2437
2859
  case 'delete_marketing_benchmark': {
2438
2860
  return successResponse(await deleteMarketingBenchmark(config, { metricRef: params['metricRef'] }));
2439
2861
  }
2862
+ case 'get_verification_ledger': {
2863
+ return successResponse(await getVerificationLedger(config, {
2864
+ window: params['window'],
2865
+ channel: params['channel'],
2866
+ onlyProblems: params['onlyProblems'],
2867
+ }));
2868
+ }
2869
+ case 'record_platform_read': {
2870
+ return successResponse(await recordPlatformRead(config, {
2871
+ channel: params['channel'],
2872
+ metric: params['metric'],
2873
+ from: params['from'],
2874
+ to: params['to'],
2875
+ value: params['value'],
2876
+ sourceName: params['sourceName'],
2877
+ note: params['note'],
2878
+ }));
2879
+ }
2880
+ case 'propose_marketing_change': {
2881
+ return successResponse(await proposeMarketingChange(config, {
2882
+ title: params['title'],
2883
+ type: params['type'],
2884
+ hypothesis: params['hypothesis'],
2885
+ reviewOn: params['reviewOn'],
2886
+ signals: params['signals'],
2887
+ runId: params['runId'],
2888
+ }));
2889
+ }
2890
+ case 'install_weekly_growth_workflow': {
2891
+ return successResponse(await installWeeklyGrowthWorkflow(config));
2892
+ }
2893
+ case 'get_growth_signals': {
2894
+ return successResponse(await getGrowthSignals(config));
2895
+ }
2896
+ case 'set_marketing_moment': {
2897
+ return successResponse(await setMarketingMoment(config, {
2898
+ key: params['key'],
2899
+ name: params['name'],
2900
+ date: params['date'],
2901
+ leadDays: params['leadDays'],
2902
+ surfaces: params['surfaces'],
2903
+ }));
2904
+ }
2905
+ case 'link_moment_change': {
2906
+ return successResponse(await linkMomentChange(config, {
2907
+ key: params['key'],
2908
+ surfaceId: params['surfaceId'],
2909
+ workItemId: params['workItemId'],
2910
+ }));
2911
+ }
2912
+ case 'add_competitor': {
2913
+ return successResponse(await addCompetitor(config, {
2914
+ appId: params['appId'],
2915
+ name: params['name'],
2916
+ country: params['country'],
2917
+ }));
2918
+ }
2919
+ case 'remove_competitor': {
2920
+ return successResponse(await removeCompetitor(config, { appId: params['appId'] }));
2921
+ }
2922
+ case 'set_tracked_keywords': {
2923
+ return successResponse(await setTrackedKeywords(config, {
2924
+ keywords: params['keywords'],
2925
+ country: params['country'],
2926
+ }));
2927
+ }
2928
+ case 'get_ai_visibility': {
2929
+ return successResponse(await getAiVisibility(config, { weeks: params['weeks'] }));
2930
+ }
2931
+ case 'set_ai_questions': {
2932
+ return successResponse(await setAiQuestions(config, {
2933
+ questions: params['questions'],
2934
+ brandTerms: params['brandTerms'],
2935
+ }));
2936
+ }
2937
+ case 'run_ai_visibility_check': {
2938
+ return successResponse(await runAiVisibilityCheck(config));
2939
+ }
2940
+ case 'create_switchback_test': {
2941
+ return successResponse(await createSwitchbackTest(config, {
2942
+ name: params['name'],
2943
+ keywordId: params['keywordId'],
2944
+ keywordText: params['keywordText'],
2945
+ weeks: params['weeks'],
2946
+ startWeek: params['startWeek'],
2947
+ weekCount: params['weekCount'],
2948
+ minN: params['minN'],
2949
+ minLift: params['minLift'],
2950
+ maxCannibalisationPct: params['maxCannibalisationPct'],
2951
+ }));
2952
+ }
2953
+ case 'start_switchback_test': {
2954
+ return successResponse(await startSwitchbackTest(config, { id: params['id'] }));
2955
+ }
2956
+ case 'get_switchback_test': {
2957
+ return successResponse(await getSwitchbackTest(config, { id: params['id'] }));
2958
+ }
2959
+ case 'list_switchback_tests': {
2960
+ return successResponse(await listSwitchbackTests(config));
2961
+ }
2962
+ case 'import_marketing_changes': {
2963
+ return successResponse(await importMarketingChanges(config, {
2964
+ filePath: params['filePath'],
2965
+ source: params['source'],
2966
+ }));
2967
+ }
2968
+ case 'get_creator_results': {
2969
+ return successResponse(await getCreatorResults(config, {
2970
+ creatorId: params['creatorId'],
2971
+ from: params['from'],
2972
+ to: params['to'],
2973
+ }));
2974
+ }
2975
+ case 'create_tracked_link': {
2976
+ return successResponse(await createTrackedLink(config, {
2977
+ kind: params['kind'],
2978
+ family: params['family'],
2979
+ token: params['token'],
2980
+ label: params['label'],
2981
+ workItemId: params['workItemId'],
2982
+ }));
2983
+ }
2984
+ case 'list_tracked_links': {
2985
+ return successResponse(await listTrackedLinks(config, {
2986
+ kind: params['kind'],
2987
+ workItemId: params['workItemId'],
2988
+ withPerformance: params['withPerformance'],
2989
+ }));
2990
+ }
2991
+ case 'tag_message': {
2992
+ return successResponse(await tagMessage(config, {
2993
+ message: params['message'],
2994
+ targetKind: params['targetKind'],
2995
+ targetRef: params['targetRef'],
2996
+ label: params['label'],
2997
+ }));
2998
+ }
2999
+ case 'untag_message': {
3000
+ return successResponse(await untagMessage(config, {
3001
+ targetKind: params['targetKind'],
3002
+ targetRef: params['targetRef'],
3003
+ }));
3004
+ }
3005
+ case 'list_promises': {
3006
+ return successResponse(await listPromises(config, {
3007
+ from: params['from'],
3008
+ to: params['to'],
3009
+ }));
3010
+ }
2440
3011
  case 'get_post_analytics': {
2441
3012
  return successResponse(await getPostAnalytics({ postId: params['postId'], since: params['since'] }, config));
2442
3013
  }
@@ -2555,13 +3126,15 @@ export async function runMcpServer() {
2555
3126
  }, config, onProgress));
2556
3127
  }
2557
3128
  case 'preview_creative': {
2558
- const result = await previewCreative({ creativeId: params['creativeId'] }, config);
3129
+ const result = await previewCreative({ creativeId: params['creativeId'], uiOverlay: params['uiOverlay'] }, config);
2559
3130
  if (result.image) {
2560
3131
  return imageResponse(result.image, {
2561
3132
  renderId: result.renderId,
2562
3133
  state: result.state,
2563
3134
  url: result.url,
2564
3135
  note: result.note,
3136
+ ...(result.checks ? { checks: result.checks, passed: result.passed } : {}),
3137
+ ...(result.overlaySheets ? { overlaySheets: result.overlaySheets } : {}),
2565
3138
  });
2566
3139
  }
2567
3140
  return successResponse(result);
@@ -2668,12 +3241,14 @@ export async function runMcpServer() {
2668
3241
  return successResponse(await updateCreativeSlideText(params, config));
2669
3242
  }
2670
3243
  case 'attach_creative_to_post': {
2671
- return successResponse(await attachCreativeToPost({
3244
+ const attached = await attachCreativeToPost({
2672
3245
  creativeId: params['creativeId'],
2673
3246
  postId: params['postId'],
2674
3247
  workItemId: params['workItemId'],
2675
3248
  renderId: params['renderId'],
2676
- }, config));
3249
+ ignoreSafeZone: params['ignoreSafeZone'],
3250
+ }, config);
3251
+ return attached['code'] === 'SAFE_ZONE_TEXT' ? errorResponse(attached) : successResponse(attached);
2677
3252
  }
2678
3253
  case 'create_experiment': {
2679
3254
  return successResponse(await createExperiment({
@@ -2702,6 +3277,11 @@ export async function runMcpServer() {
2702
3277
  return errorResponse(message);
2703
3278
  }
2704
3279
  });
3280
+ // The OCR worker (safe-zone checks) stays warm for the session and is stopped when the client disconnects,
3281
+ // so the process can exit.
3282
+ server.onclose = () => {
3283
+ void closeOcr().catch(() => { });
3284
+ };
2705
3285
  const transport = new StdioServerTransport();
2706
3286
  await server.connect(transport);
2707
3287
  }