@sentientui/mcp 0.19.0 → 0.21.0

package/dist/{chunk-HT23NB6F.js → chunk-K7JN3LOH.js}

@@ -21,9 +21,10 @@ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 
 // src/api-client.ts
 var ApiError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, detail) {
     super(message);
     this.status = status;
+    this.detail = detail;
     this.name = "ApiError";
   }
 };
@@ -40,8 +41,14 @@ var ApiClient = class {
   async post(path, body) {
     return this.request("POST", path, body);
   }
+  async patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  async delete(path, body) {
+    return this.request("DELETE", path, body);
+  }
   async request(method, path, body, isRetry = false) {
-    var _a, _b;
+    var _a, _b, _c;
     const res = await fetch(`${this.baseUrl}/v1/mgmt${path}`, {
       method,
       headers: __spreadValues({
@@ -58,7 +65,9 @@ var ApiClient = class {
         return this.request(method, path, body, true);
       }
     }
-    throw new ApiError(res.status, String((_b = (_a = errBody.error) != null ? _a : errBody.message) != null ? _b : res.statusText));
+    const code = String((_b = (_a = errBody.error) != null ? _a : errBody.message) != null ? _b : res.statusText);
+    const human = (_c = errBody.message) != null ? _c : errBody.reason;
+    throw new ApiError(res.status, code, typeof human === "string" && human !== code ? human : void 0);
   }
 };
 
@@ -403,7 +412,7 @@ function localDate(iso, timeZone) {
 }
 function apiErrorGuidance(err, extra) {
   if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
-    return extra[err.message];
+    return extra[err.message] + detailSuffix(err);
   }
   switch (err.message) {
     case "insufficient_scope":
@@ -412,6 +421,15 @@ function apiErrorGuidance(err, extra) {
       return "Demo mode is read-only. Create a SentientUI account and sign in (or use a project server key) to make changes.";
     case "insufficient_role":
       return "Your account role does not permit this action \u2014 it needs the account owner or an admin.";
+    // The mgmt write routes answer a viewer with `role_required` (and origins
+    // with `not_authorized`), not `insufficient_role` — so every role refusal
+    // fell through to the generic 403 "check your key has access" advice and
+    // sent the agent re-authenticating for a permission it already had wrong.
+    case "role_required":
+    case "not_authorized":
+      return `Your role on this project cannot make this change \u2014 it needs an editor or admin.${detailSuffix(err)}`;
+    case "ai_unavailable":
+      return "AI generation is unavailable on the SentientUI server right now (no model is configured). Nothing was queued \u2014 retry later.";
     default:
       break;
   }
@@ -443,10 +461,25 @@ function apiErrorGuidance(err, extra) {
     return `This feature requires a higher plan (${err.message}). Upgrade your SentientUI plan, then try again.`;
   }
   if (err.status === 403) {
-    return `Access denied (${err.message}). Check that your key or login has access to this project.`;
+    return `Access denied (${err.message}). Check that your key or login has access to this project.${detailSuffix(err)}`;
+  }
+  if (err.status === 404) {
+    return `Not found (${err.message}). The project, component, variant, goal or cell does not exist, or this credential cannot see it (an sk_ server key sees only its own project). Re-read the ids with list_projects, list_components, list_goals or get_cell_matrix and retry with an exact id.` + detailSuffix(err);
+  }
+  if (err.status === 400) {
+    return `The API rejected the arguments (${err.message}).${detailSuffix(err)} Correct the input and retry \u2014 repeating the same call will fail the same way.`;
+  }
+  if (err.status === 409) {
+    return `Conflict (${err.message}): the target's current state does not allow this.${detailSuffix(err)} Read its current state first, then retry the step that makes this valid.`;
+  }
+  if (err.status === 502 || err.status === 503 || err.status === 504) {
+    return `SentientUI is temporarily unavailable (${err.status} ${err.message}). Nothing changed \u2014 wait a moment and retry.`;
   }
   return null;
 }
+function detailSuffix(err) {
+  return err.detail ? ` Server says: ${untrusted(err.detail, 300)}` : "";
+}
 async function settled(p) {
   try {
     return { ok: true, value: await p };
@@ -559,6 +592,37 @@ function registerProjectTools(server, client) {
       };
     }, CREATE_PROJECT_GUIDANCE)
   );
+  server.registerTool(
+    "add_origin",
+    {
+      title: "Add allowed origin",
+      description: "Allow-list a site origin (scheme + host, e.g. https://www.example.com) so the SDK's events from it are accepted. Idempotent: an origin already on the list is left as is. Removing an origin is dashboard-only. Needs an editor/admin login or the project's sk_ server key. Confirm the exact origin with the user first \u2014 an allowed origin can send events into this project.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        origin: z2.string().min(1).max(500).describe("The site origin, e.g. https://www.example.com (a pasted page URL is reduced to its origin)")
+      },
+      outputSchema: {
+        origins: z2.array(z2.string()).describe("The full allow-list after the change")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, origin }) => {
+      var _a;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/origins`, { origin });
+      const origins = (_a = res.origins) != null ? _a : [];
+      return {
+        content: [{
+          type: "text",
+          text: `Allowed origins: ${origins.map((o) => untrusted(o)).join(", ") || "(none)"}. Events from these origins are accepted (other API instances pick the change up within ~30 seconds, when their key cache expires).`
+        }],
+        structuredContent: { origins }
+      };
+    }, {
+      invalid_origin: "That is not a usable origin. Pass a scheme and host, e.g. https://www.example.com.",
+      origin_required: "An origin is required, e.g. https://www.example.com."
+    })
+  );
   server.registerTool(
     "list_projects",
     {
@@ -603,13 +667,16 @@ function registerProjectTools(server, client) {
     "get_project_stats",
     {
       title: "Project health stats",
-      description: "Get health stats for a project: event volume, session count, agent calls, and status.",
+      description: "Get ingestion health for a project: status, events and sessions in the last 24 hours, the time of the last event, and the all-time count of calls to the SentientUI agent API (/v1/agent) \u2014 NOT MCP tool calls.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
         status: z2.string().describe("Overall project health status"),
         events24h: z2.number().describe("Events in the last 24 hours"),
         sessions24h: z2.number().describe("Sessions in the last 24 hours"),
-        agentCalls: z2.number().describe("Total agent (MCP/API) calls"),
+        // Was "Total agent (MCP/API) calls" — but the count comes from
+        // agent_events, which only the /v1/agent endpoint writes. MCP tool calls
+        // are never in it, so an agent read its own activity as missing.
+        agentCalls: z2.number().describe("All-time calls to the /v1/agent agent API (not MCP tool calls)"),
         lastEventAt: z2.string().nullable().describe("ISO timestamp of the last event, or null")
       },
       annotations: {
@@ -626,7 +693,7 @@ function registerProjectTools(server, client) {
         `Status: ${stats.status}`,
         `Events (24h): ${stats.events24h}`,
         `Sessions (24h): ${stats.sessions24h}`,
-        `Agent calls (total): ${stats.agentCalls}`,
+        `Agent API calls (/v1/agent, all-time): ${stats.agentCalls}`,
         `Last event: ${(_a = stats.lastEventAt) != null ? _a : "never"}`
       ].join("\n");
       return {
@@ -653,6 +720,10 @@ var EVIDENCE_LABEL = {
   early_signal: "Early signal (still moving \u2014 not a result)",
   moderate_evidence: "Moderate evidence (about one call in five of this strength is wrong \u2014 not decided)",
   strong_evidence: "Strong evidence",
+  // The mirror of moderate_evidence. Before the server had it, an arm clearly
+  // behind its baseline read "Inconclusive (… without separating)" — it HAD
+  // separated, downward.
+  likely_worse: "Likely worse than the baseline (about one call in five of this strength is wrong \u2014 not decided)",
   inconclusive: "Inconclusive (ran a full period without separating from the baseline)"
 };
 var STATES = new Set(Object.keys(EVIDENCE_LABEL));
@@ -703,7 +774,9 @@ function verdictOf(state, stats, isBaseline) {
 var VERDICT_TEXT = {
   ahead: "reliably AHEAD of the baseline",
   behind: "reliably BEHIND the baseline",
-  unclear: "not separated from the baseline",
+  // "not RELIABLY": this is printed beside moderate_evidence and likely_worse
+  // labels too, and a bare "not separated" contradicted the label next to it.
+  unclear: "not reliably separated from the baseline",
   no_evidence: "no evidence available from the server"
 };
 function rateWithN(conversions, n, unit = "sessions") {
@@ -789,7 +862,7 @@ function registerComponentTools(server, client) {
             conversions: z3.number().describe("Converting sessions in the window"),
             currentCvr: z3.number().nullable().describe("conversions / sessions over the window (0-1); null at 0 sessions"),
             lowSample: z3.boolean().describe(`True under ${MIN_EVIDENCE_SAMPLE} sessions \u2014 the rate is not interpretable on its own`),
-            evidenceState: z3.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
+            evidenceState: z3.string().nullable().describe("Reliability (all time): the server's ALL-TIME evidence state vs the baseline on direct evidence \u2014 not_enough_data | early_signal | moderate_evidence | strong_evidence | likely_worse | inconclusive; null for the baseline or when not provided. Not a verdict on the windowed rate"),
             probBeatsBaseline: z3.number().nullable().describe("P(this arm > baseline), all-time, from the server; null when not provided"),
             reliabilityVerdict: z3.enum(["baseline", "ahead", "behind", "unclear", "no_evidence"]).describe("The all-time verdict read from evidenceState \u2014 reliability (all time), which can differ from `verdict` on the window"),
             windowEvidenceState: z3.string().nullable().describe("The server's evidence state on the WINDOWED session conversion rate vs the baseline; null for the baseline, when the arm was not scored in the window, or on older APIs"),
@@ -1107,7 +1180,10 @@ function registerPersonaTools(server, client) {
     "get_persona_breakdown",
     {
       title: "Persona breakdown",
-      description: "Get the distribution of visitor persona clusters with session counts and reliability scores." + UNTRUSTED_FIELDS_NOTE,
+      // Takes no range/from/to on purpose: the API computes it over every
+      // retained session and has no window. Saying so stops an agent from
+      // reading it beside a 7d get_variant_performance as the same period.
+      description: "Get the distribution of visitor persona clusters with session counts and reliability scores, over ALL retained human sessions (not windowed \u2014 this has no range input, unlike the conversion tools)." + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("persona-breakdown"),
       outputSchema: {
@@ -1168,8 +1244,13 @@ function registerGoalTools(server, client) {
   server.registerTool(
     "get_goal_funnel",
     {
-      title: "Goal funnel",
-      description: "Get goal hit counts and unique-session conversion rates for a window (default: last 30 calendar days), plus a per-variant breakdown. NOTE: the per-variant completionRate values are ALL-TIME (bounded only by plan retention), NOT windowed \u2014 a variant completion rate needs the full assignment history as its denominator, so it does not change when you narrow `range`, and retired components keep appearing in it. Only hits/uniqueSessions/conversionRate/revenue respect the window. This is a flat per-goal list \u2014 for multi-step funnel drop-off, use get_funnel_report." + UNTRUSTED_FIELDS_NOTE,
+      // Named get_goal_funnel for compatibility (renaming a published tool
+      // breaks every saved prompt and host allow-list), but it is NOT a funnel:
+      // agents asked it for step drop-off and reported per-goal rates as funnel
+      // stages. The title and the first words of the description now say what
+      // it is, and point to the real funnel tool.
+      title: "Goal conversions (per goal \u2014 not a step funnel)",
+      description: "Per-goal conversion summary \u2014 NOT a step funnel (for step-by-step drop-off use list_funnels + get_funnel_report). Gets goal hit counts and unique-session conversion rates for a window (default: last 30 calendar days), plus a per-variant breakdown. NOTE: the per-variant completionRate values are ALL-TIME (bounded only by plan retention), NOT windowed \u2014 a variant completion rate needs the full assignment history as its denominator, so it does not change when you narrow `range`, and retired components keep appearing in it. Only hits/uniqueSessions/conversionRate/revenue respect the window. Per-variant rates are descriptive, not joined to the evidence verdicts \u2014 for whether an arm is ahead, use get_variant_performance." + UNTRUSTED_FIELDS_NOTE,
       inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       _meta: uiMeta("goal-funnel"),
       outputSchema: {
@@ -1350,6 +1431,51 @@ function registerGoalTools(server, client) {
       return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
     })
   );
+  server.registerTool(
+    "define_goal",
+    {
+      title: "Define a new goal",
+      description: "Create a NEW goal (conversion signal) for a project. Create-only: it never changes an existing goal \u2014 an id that already exists, including an archived one, is refused (goal_exists); call list_goals first. It never sets or changes the PRIMARY goal (what experiments optimize): the goal is created as 'secondary' (default) or 'guardrail'; choosing the primary stays a dashboard decision. A guardrail goal can pause variants that hurt it \u2014 say so when proposing one. Event types: url_reached (needs urlPattern, e.g. /thank-you), click / form_submit (need a locator, usually easier to pick in the dashboard on-site editor, or fire from code with client.goal('<goalId>') instead), scroll_depth (needs threshold in (0, 1]). Needs an editor/admin login or the project's sk_ server key. Confirm the goal id, event and pattern with the user before calling.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        goalId: z6.string().min(1).max(128).refine((s) => !s.startsWith("funnel:"), "'funnel:' is reserved for funnel bindings").describe("Stable id code will reference, e.g. 'signup' or 'checkout-complete'. Must not exist yet."),
+        event: z6.enum(["url_reached", "click", "form_submit", "scroll_depth"]).describe("What counts as a conversion"),
+        urlPattern: z6.string().min(1).max(512).optional().describe("url_reached only: the path pattern, e.g. '/thank-you' or '/orders/*'"),
+        locator: z6.record(z6.unknown()).optional().describe('click / form_submit only: the element locator (e.g. { "id": "signup-button" })'),
+        threshold: z6.number().gt(0).max(1).optional().describe("scroll_depth only: how far down the page counts, in (0, 1]"),
+        displayName: z6.string().min(1).max(128).optional().describe("Human-readable name shown in the dashboard"),
+        role: z6.enum(["secondary", "guardrail"]).optional().describe("secondary (default) is tracked and reported; guardrail can also pause variants that hurt it. Never 'primary'."),
+        defaultValue: z6.number().positive().max(1e9).optional().describe("Fixed worth of one conversion in the project currency (revenue goals)")
+      },
+      outputSchema: {
+        goalId: z6.string(),
+        role: z6.enum(["secondary", "guardrail"]).describe("Never primary \u2014 this tool cannot change the primary goal")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, goalId, event, urlPattern, locator, threshold, displayName, role, defaultValue }) => {
+      var _a, _b, _c;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/goal-definitions`, __spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues(__spreadValues({
+        goalId,
+        event
+      }, urlPattern !== void 0 ? { urlPattern } : {}), locator !== void 0 ? { locator } : {}), threshold !== void 0 ? { threshold } : {}), displayName !== void 0 ? { displayName } : {}), role !== void 0 ? { role } : {}), defaultValue !== void 0 ? { defaultValue } : {}));
+      const structuredContent = { goalId: (_a = res.goalId) != null ? _a : goalId, role: (_c = (_b = res.role) != null ? _b : role) != null ? _c : "secondary" };
+      return {
+        content: [{
+          type: "text",
+          text: `Created goal ${untrusted(structuredContent.goalId)} (${structuredContent.role}, ${event}). It is active now. The primary goal was not changed \u2014 if this should be what experiments optimize, the owner can make it primary in the dashboard. Reference the goalId verbatim from code (client.goal('<goalId>')) if the event is not tracked automatically.`
+        }],
+        structuredContent
+      };
+    }, {
+      goal_exists: "A goal with this id already exists (it may be archived). define_goal never changes an existing goal \u2014 pick a new id (see list_goals), or edit that goal in the dashboard.",
+      primary_not_allowed: "define_goal never sets the primary goal. Create it as secondary; the owner can make it primary in the dashboard.",
+      invalid_goal_id: "That goal id is not allowed: use 1-128 characters, and not the reserved 'funnel:' prefix.",
+      invalid_goal: "The goal definition is incomplete for its event type: url_reached needs urlPattern, click/form_submit need a locator, scroll_depth needs threshold.",
+      "Not Found": "This SentientUI API does not support creating goals from MCP yet (it predates create-only goals). Define the goal in the dashboard instead."
+    })
+  );
 }
 
 // src/tools/funnels.ts
@@ -1559,7 +1685,9 @@ function registerLayoutTools(server, client) {
     "get_layout_stats",
     {
       title: "Layout stats",
-      description: "Get per-persona section layout rankings and bandit reward weights." + UNTRUSTED_FIELDS_NOTE,
+      // No window by design: these are the bandit's cumulative pulls and reward,
+      // the state serving reads — not a report over a period.
+      description: "Get per-persona section layout rankings with bandit pulls and average reward \u2014 the cumulative learning state serving uses (not windowed; there is no range input). avgReward is a reward signal, not a conversion rate." + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       _meta: uiMeta("layout-stats"),
       outputSchema: {
@@ -1611,7 +1739,7 @@ function registerVariantWriteTools(server, client) {
     "create_variant",
     {
       title: "Create managed variant",
-      description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
+      description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Works on every plan with an editor/admin login or the project's sk_ server key (anonymous demo tokens are read-only). The variant is created as a DRAFT \u2014 it serves no traffic until activated with update_variant (status 'active'). Confirm the text with the user before calling.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: z10.string().min(1).max(200).describe("The component ID to add a variant to"),
@@ -1645,7 +1773,7 @@ function registerVariantWriteTools(server, client) {
       return {
         content: [{
           type: "text",
-          text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is in draft state \u2014 activate it from the dashboard. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
+          text: `Managed text variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}${contentNote}. It is a draft and serves no traffic yet \u2014 after the user confirms, activate it with update_variant (status 'active'), or delete it with delete_variant_draft. Reminder: this is a no-code managed variant; for code-native variants, edit the code instead (see get_variant_brief).`
         }],
         structuredContent: {
           variantId: result.variantId,
@@ -1661,20 +1789,24 @@ function registerVariantWriteTools(server, client) {
     "pause_variant",
     {
       title: "Pause variant",
-      description: "Pause a variant, stopping traffic from being assigned to it.",
+      description: "Pause a variant: no new traffic is assigned to it until it is resumed. This changes what live visitors see, so CONFIRM with the user before calling. Undo with resume_variant.",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: z10.string().describe("The component ID"),
-        variantId: z10.string().describe("The variant ID to pause")
+        componentId: z10.string().min(1).max(200).describe("The component ID"),
+        variantId: z10.string().min(1).max(200).describe("The variant ID to pause")
       },
       outputSchema: {
         variantId: z10.string(),
         componentId: z10.string(),
         paused: z10.literal(true).describe("The variant is now paused")
       },
+      // destructiveHint was false, so hosts that gate destructive tools behind a
+      // confirmation ran this without asking — yet it pulls a live arm out of
+      // serving for every visitor. It is reversible (resume_variant), but the
+      // hint is about the change to the environment, not about undo.
       annotations: {
         readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
       }
@@ -1685,17 +1817,194 @@ function registerVariantWriteTools(server, client) {
       return {
         content: [{
           type: "text",
-          text: `Variant ${variantId} in component ${componentId} has been paused. No new traffic will be assigned to it.`
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is paused. No new traffic will be assigned to it. Undo with resume_variant.`
         }],
         structuredContent: { variantId, componentId, paused: true }
       };
     })
   );
+  server.registerTool(
+    "resume_variant",
+    {
+      title: "Resume variant",
+      description: "Resume a paused variant so it is assigned traffic again \u2014 works for a manual pause (pause_variant) and for a guardrail auto-pause (see list_guardrail_events). Resuming a guardrail-paused arm puts a variant the guardrail judged harmful back in front of visitors, so CONFIRM with the user first.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: z10.string().min(1).max(200).describe("The component ID"),
+        variantId: z10.string().min(1).max(200).describe("The paused variant ID to resume")
+      },
+      outputSchema: {
+        variantId: z10.string(),
+        componentId: z10.string(),
+        paused: z10.literal(false).describe("The variant is no longer paused")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/guardrails/${encodeURIComponent(componentId)}/unpause`, {
+        variantIds: [variantId]
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is resumed and will be assigned traffic again.`
+        }],
+        structuredContent: { variantId, componentId, paused: false }
+      };
+    })
+  );
+  server.registerTool(
+    "update_variant",
+    {
+      title: "Update managed variant",
+      description: "Edit a NO-CODE managed variant (one created with create_variant or in the dashboard): its display name, its text, or its status \u2014 'active' starts serving it to visitors, 'draft' takes it back out of rotation. Code-native variants cannot be edited here (change the code). Overwriting text or activating changes what live visitors see, so CONFIRM with the user first. Omit a field to leave it unchanged.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: z10.string().min(1).max(200).describe("The component ID"),
+        variantId: z10.string().min(1).max(200).describe("The managed variant ID (dm_\u2026)"),
+        displayName: z10.string().min(1).max(200).optional().describe("New display name"),
+        content: z10.string().max(1e4).optional().describe("New text content (replaces the old text)"),
+        status: z10.enum(["draft", "active"]).optional().describe("'active' serves it; 'draft' stops serving it")
+      },
+      outputSchema: {
+        variantId: z10.string(),
+        componentId: z10.string(),
+        changed: z10.array(z10.string()).describe("Fields that were sent for update"),
+        status: z10.enum(["draft", "active"]).nullable().describe("The new status, or null when unchanged")
+      },
+      // Destructive: the previous text is overwritten, not versioned.
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId, displayName, content, status }) => {
+      const changed = [
+        ...displayName !== void 0 ? ["displayName"] : [],
+        ...content !== void 0 ? ["content"] : [],
+        ...status !== void 0 ? ["status"] : []
+      ];
+      if (changed.length === 0) {
+        return {
+          content: [{ type: "text", text: "Nothing to update \u2014 pass displayName, content and/or status." }],
+          isError: true
+        };
+      }
+      const id = encodeURIComponent(projectId);
+      await client.patch(`/projects/${id}/variants`, { componentId, variantId, displayName, content, status });
+      const statusNote = status === "active" ? " It is now ACTIVE and will be assigned traffic." : status === "draft" ? " It is now a draft and no longer serves traffic." : "";
+      return {
+        content: [{
+          type: "text",
+          text: `Managed variant ${untrusted(variantId)} in component ${untrusted(componentId)} updated (${changed.join(", ")}).${statusNote}`
+        }],
+        structuredContent: { variantId, componentId, changed, status: status != null ? status : null }
+      };
+    }, {
+      // PATCH matches managed variants only, so a code-native id answers a
+      // bare not_found that read as "that variant does not exist".
+      not_found: "No MANAGED variant with that id exists in this component. Code-native variants (declared in <Adaptive variants>) are edited in the code, not here \u2014 check ids with list_components (a wrong projectId answers the same way)."
+    })
+  );
+  server.registerTool(
+    "delete_variant_draft",
+    {
+      title: "Delete draft variant",
+      description: "Permanently delete a managed variant that is still a DRAFT (never activated). Active variants cannot be deleted \u2014 pause or retire them instead. CONFIRM with the user first: this cannot be undone.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: z10.string().min(1).max(200).describe("The component ID"),
+        variantId: z10.string().min(1).max(200).describe("The draft managed variant ID (dm_\u2026)")
+      },
+      outputSchema: {
+        variantId: z10.string(),
+        componentId: z10.string(),
+        deleted: z10.literal(true)
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.delete(`/projects/${id}/variants`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Draft variant ${untrusted(variantId)} in component ${untrusted(componentId)} was deleted.`
+        }],
+        structuredContent: { variantId, componentId, deleted: true }
+      };
+    }, {
+      // The API's DELETE matches managed drafts only, so an active or
+      // code-native variant answers a bare not_found — say why.
+      not_found: "No managed DRAFT variant with that id exists in this component. Active and code-native variants cannot be deleted \u2014 use pause_variant or retire_variant instead (check ids with list_components; a wrong projectId answers the same way)."
+    })
+  );
+  server.registerTool(
+    "retire_variant",
+    {
+      title: "Retire variant",
+      description: "Retire (archive) an ACTIVE variant: it stops serving and moves to the archived list. Works for code-native variants that were removed from the code and linger. A promoted (pinned) variant must be unpromoted in the dashboard first. CONFIRM with the user first; undo with restore_variant.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: z10.string().min(1).max(200).describe("The component ID"),
+        variantId: z10.string().min(1).max(200).describe("The active variant ID to retire")
+      },
+      outputSchema: {
+        variantId: z10.string(),
+        componentId: z10.string(),
+        status: z10.literal("retired")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/variants/retire`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is retired and no longer serves. Undo with restore_variant.`
+        }],
+        structuredContent: { variantId, componentId, status: "retired" }
+      };
+    }, {
+      variant_promoted: "This variant is promoted (pinned as the winner), so it cannot be retired. Unpromote it in the dashboard first, then retry.",
+      not_found: "No ACTIVE variant with that id exists in this component (it may already be retired, or still a draft), or the projectId is wrong. Check ids with list_components."
+    })
+  );
+  server.registerTool(
+    "restore_variant",
+    {
+      title: "Restore variant",
+      description: "Bring a RETIRED variant back to active so it serves again. For a managed draft that was never activated use update_variant (status 'active') instead. Restoring does not clear a pause \u2014 use resume_variant for that. CONFIRM with the user first.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        componentId: z10.string().min(1).max(200).describe("The component ID"),
+        variantId: z10.string().min(1).max(200).describe("The retired variant ID to restore")
+      },
+      outputSchema: {
+        variantId: z10.string(),
+        componentId: z10.string(),
+        status: z10.literal("active")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, componentId, variantId }) => {
+      const id = encodeURIComponent(projectId);
+      await client.post(`/projects/${id}/variants/restore`, { componentId, variantId });
+      return {
+        content: [{
+          type: "text",
+          text: `Variant ${untrusted(variantId)} in component ${untrusted(componentId)} is active again. If it was also paused, call resume_variant.`
+        }],
+        structuredContent: { variantId, componentId, status: "active" }
+      };
+    })
+  );
   server.registerTool(
     "refresh_insights",
     {
       title: "Refresh insights",
-      description: "Trigger fresh AI insight generation for a project. Returns immediately; use get_insights in ~15 seconds to see results.",
+      // The plan and role gates were undocumented, so agents on Free called it
+      // and got a bare 403 they could not explain to the user.
+      description: "Trigger fresh AI insight generation for a project (a paid model call). Needs the Starter plan or higher and an editor/admin role (anonymous demo tokens are read-only); advisor recommendations additionally need Growth or higher. Returns immediately; call get_insights in ~15 seconds to see results.",
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
         projectId: z10.string(),
@@ -1747,11 +2056,21 @@ var BEST_PRACTICE_PRIORS = {
     "Make the CTA specific and benefit-led.",
     "Add a single strong proof point; remove competing distractions."
   ],
-  marketplace: [
-    "Reduce choice overload: guide the visitor to a clear next step.",
-    "Surface trust and liquidity signals (ratings, counts, recency).",
-    "Make the primary action on each listing obvious.",
-    "Reassure on safety/guarantees near the point of decision."
+  // Keys must be the project context types the API accepts (projects.ts
+  // VALID_CONTEXT_TYPES: saas | ecommerce | marketing | landing | internal).
+  // A `marketplace` key sat here that no project could ever have, while
+  // marketing and internal projects silently fell through to the generic list.
+  marketing: [
+    'Make the page answer "what is this and why should I care" in the first screen.',
+    "Give each section one job and one next step; cut competing CTAs.",
+    "Put the strongest proof (named customers, a hard number) near the primary CTA.",
+    "Match the copy to where the visitor came from (campaign, search intent)."
+  ],
+  internal: [
+    "Optimize for task completion, not persuasion: make the next step obvious.",
+    "Reduce steps and fields; prefill what the system already knows.",
+    "Use plain, specific labels over marketing copy.",
+    "Make errors and empty states say exactly what to do next."
   ]
 };
 var GENERIC_PRIORS = [
@@ -1784,7 +2103,10 @@ function guidanceFor(dataState, contextType, arms) {
     }
     case "directional": {
       const inconclusive = arms.some((a) => a.state === "inconclusive");
-      return 'No comparison on this component is decided. Early and moderate signals are hypotheses, not results (moderate evidence is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 the existing versions do not differ meaningfully, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
+      const likelyWorse = arms.filter((a) => !a.isBaseline && a.state === "likely_worse").map((a) => untrusted(a.variantId));
+      return 'No comparison on this component is decided. Early, moderate and likely-worse signals are hypotheses, not results (each is wrong about one time in five), so do not target an arm as "under-" or "out-performing". ' + (likelyWorse.length ? `Probably behind the baseline (not decided): ${likelyWorse.join(", ")} \u2014 do not build on ${likelyWorse.length === 1 ? "it" : "them"}. ` : "") + // "did not separate" is not "do not differ": the old wording asserted
+      // an equality the evidence never measured.
+      (inconclusive ? "At least one arm ran a full period without separating from the baseline \u2014 any difference between the existing versions is too small to detect, so make a clearly different change rather than a tweak. " : "") + "Lean on the best-practice priors below and make one focused change.";
     }
     case "collecting":
       if (!arms.some((a) => !a.isBaseline)) {
@@ -2282,12 +2604,12 @@ function registerAgentTrafficTools(server, client) {
     "get_agent_traffic",
     {
       title: "Agent traffic",
-      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 days; pass from/to for a custom period (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate." + UNTRUSTED_FIELDS_NOTE,
-      inputSchema: {
-        projectId: projectIdSchema,
-        from: z14.string().optional().describe("Period start (ISO 8601 date or timestamp). Defaults to 30 days ago."),
-        to: z14.string().optional().describe("Period end (ISO 8601 date or timestamp). Defaults to now.")
-      },
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Defaults to the last 30 calendar days; pass range (7d/30d/90d/all) or from/to (YYYY-MM-DD) like every other windowed tool (agent logs are retained 30 days on Free/Starter, 90 on Growth+). Agent traffic is tracked separately and never counted in conversion rate." + UNTRUSTED_FIELDS_NOTE,
+      // This tool alone took ad-hoc ISO from/to with no range token and echoed
+      // no window, while every other windowed tool used rangeInputSchema — so
+      // agents passed range:'7d' here, it was silently dropped, and 30 days of
+      // traffic was reported as a week. The endpoint uses the shared resolver.
+      inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       outputSchema: {
         totals: z14.object({ crawler: z14.number(), api: z14.number(), browser: z14.number() }),
         engines: z14.array(
@@ -2301,20 +2623,18 @@ function registerAgentTrafficTools(server, client) {
           })
         ),
         intents: z14.object({ user: z14.number(), search: z14.number(), training: z14.number(), other: z14.number() }).describe("Crawler fetches by purpose: user = an assistant answering a real person live"),
-        topPaths: z14.array(z14.object({ path: z14.string(), count: z14.number(), engines: z14.number() }))
+        topPaths: z14.array(z14.object({ path: z14.string(), count: z14.number(), engines: z14.number() })),
+        window: windowOutputSchema
       },
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
-    withApiErrorGuidance(async ({ projectId, from, to }) => {
+    withApiErrorGuidance(async ({ projectId, range, from, to }) => {
       const id = encodeURIComponent(projectId);
-      const qs = new URLSearchParams();
-      if (from) qs.set("from", from);
-      if (to) qs.set("to", to);
-      const query = qs.toString();
       const s = await client.get(
-        `/projects/${id}/agent-activity/summary${query ? `?${query}` : ""}`
+        `/projects/${id}/agent-activity/summary${rangeQuery({ range, from, to })}`
       );
-      const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths };
+      const structuredContent = { totals: s.totals, engines: s.engines, intents: s.intents, topPaths: s.topPaths, window: s.window };
+      const win = windowLine(s.window);
       const total = s.totals.crawler + s.totals.api + s.totals.browser;
       if (total === 0) {
         return {
@@ -2326,6 +2646,7 @@ function registerAgentTrafficTools(server, client) {
         };
       }
       const lines = [
+        ...win ? [win] : [],
         `Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} agentic browser sessions.`,
         `Live user fetches: ${s.intents.user} \xB7 Search index: ${s.intents.search} \xB7 Training: ${s.intents.training}${s.intents.other ? ` \xB7 Other: ${s.intents.other}` : ""} (a "live user fetch" = an AI assistant reading your site to answer a real person).`,
         "",
@@ -2416,7 +2737,7 @@ var personaOutput = z15.object({
 var cellOutput = z15.object({
   slotId: z15.string(),
   persona: z15.string(),
-  status: z15.string().describe("pending | generating | live | error | rejected"),
+  status: z15.string().describe("pending | generating | review (waiting for approval) | live | error | rejected"),
   requestedBy: z15.string(),
   armId: z15.string().nullable(),
   rationale: z15.string().nullable(),
@@ -2456,6 +2777,10 @@ function registerCellTools(server, client) {
         personas: z15.array(personaOutput),
         cells: z15.array(cellOutput),
         autoFill: z15.boolean(),
+        // The API has always sent this; without it in the schema zod stripped
+        // it, and generate_cell had no way to know a version would wait for a
+        // human instead of publishing.
+        reviewMode: z15.boolean().optional().describe("True when generated versions wait for approval (review_cell) instead of publishing automatically"),
         // Nullable: a project with no persona set at all reports null, not a
         // string. That is the NORMAL state since the default vocabulary was
         // emptied, so a non-nullable schema failed output validation on most
@@ -2472,7 +2797,7 @@ function registerCellTools(server, client) {
       const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
       const lines = [
         `Slots: ${data.slots.map((s) => `${untrusted(s.displayName)}${s.live === false ? " [draft]" : ""}`).join(", ") || "(none published)"}`,
-        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 persona source: ${(_a = data.personaSource) != null ? _a : 'none (one "everyone" row)'}`
+        `Auto-fill on first miss: ${data.autoFill ? "ON" : "off"} \xB7 review before publishing: ${data.reviewMode ? "ON (approve with review_cell)" : "off"} \xB7 persona source: ${(_a = data.personaSource) != null ? _a : 'none (one "everyone" row)'}`
       ];
       for (const p of data.personas) {
         const states = data.slots.map((s) => {
@@ -2557,7 +2882,12 @@ function registerCellTools(server, client) {
     "generate_cell",
     {
       title: "Generate a cell version",
-      description: "Queue AI generation of a version for one (persona, slot) cell. The worker writes it asynchronously (usually under a minute), brand-locked, and it goes live as a named option the optimizer explores. Also works to regenerate or retry a failed cell. Requires a paid plan (anonymous demo tokens are read-only).",
+      // The old copy promised "goes live, usually under a minute" — but with
+      // review mode on the worker parks the version for a human (status
+      // 'review') and nothing serves until someone approves it, and the queue
+      // can defer a cell (retry backoff, the plan's monthly generation cap). An
+      // agent relayed "it's live" for versions no visitor would ever see.
+      description: "Queue AI generation of a version for one (persona, slot) cell; the worker writes it asynchronously, brand-locked. If the project has review mode on, the finished version WAITS for approval (list_cell_reviews / review_cell) and serves nobody until approved; otherwise it publishes automatically as a named option the optimizer explores. Also regenerates or retries a failed cell. Generation volume is capped per plan (Free included). Check get_cell_matrix for progress. Confirm with the user before calling \u2014 each generation is a model call against the plan quota.",
       inputSchema: {
         projectId: projectIdSchema,
         slotId: z15.string().min(1).max(128).describe("The slot id (a matrix column)"),
@@ -2566,28 +2896,130 @@ function registerCellTools(server, client) {
       outputSchema: {
         slotId: z15.string(),
         persona: z15.string(),
-        status: z15.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress")
+        status: z15.literal("pending").describe("Queued \u2014 check get_cell_matrix for progress"),
+        reviewMode: z15.boolean().nullable().describe("True: the version will wait for review_cell approval. False: it publishes automatically. Null: could not be read.")
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
       const id = encodeURIComponent(projectId);
       await client.post(`/projects/${id}/cells/generate`, { slotId, persona });
+      const matrix = await settled(client.get(`/projects/${id}/cells`));
+      const reviewMode = matrix.ok && typeof matrix.value.reviewMode === "boolean" ? matrix.value.reviewMode : null;
+      const next = reviewMode === true ? "Review mode is ON: when it is written it will WAIT for approval and serve nobody until then \u2014 list it with list_cell_reviews and approve or reject it with review_cell (after the user decides)." : reviewMode === false ? "Review mode is off: once written it publishes automatically and the optimizer starts exploring it." : 'Could not read whether review mode is on \u2014 check get_cell_matrix: status "review" means it is waiting for approval (review_cell), "live" means it is serving.';
       return {
         content: [
           {
             type: "text",
-            text: `Writing a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)} \u2014 it usually goes live in under a minute. Check get_cell_matrix (status flips pending \u2192 live) or get_cell_detail for the story once it lands.`
+            text: `Queued a version of ${untrusted(slotId, 64)} for ${untrusted(persona, 64)}. It is written asynchronously (the queue may defer it \u2014 retries back off, and the plan caps generations). ${next} Track it with get_cell_matrix or get_cell_detail.`
           }
         ],
-        structuredContent: { slotId, persona, status: "pending" }
+        structuredContent: { slotId, persona, status: "pending", reviewMode }
+      };
+    })
+  );
+  server.registerTool(
+    "list_cell_reviews",
+    {
+      title: "Versions waiting for review",
+      description: "Generated versions waiting for approval (review mode): which slot and visitor type, the proposed text or layout, and why it was written. Approve or reject each with review_cell after the user decides." + UNTRUSTED_FIELDS_NOTE,
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        reviews: z15.array(
+          z15.object({
+            slotId: z15.string(),
+            slotName: z15.string(),
+            persona: z15.string(),
+            personaDisplay: z15.string(),
+            content: z15.string().nullable().describe("Proposed text, when the version is text (null for a block/layout version)"),
+            rationale: z15.string().nullable(),
+            refinedFrom: z15.string().nullable().describe("Live version this one would replace; that version keeps serving until approval"),
+            updatedAt: z15.string()
+          })
+        )
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      var _a;
+      const id = encodeURIComponent(projectId);
+      const data = await client.get(`/projects/${id}/cell-reviews`);
+      const reviews = ((_a = data.reviews) != null ? _a : []).map((r) => {
+        var _a2, _b, _c;
+        return {
+          slotId: r.slotId,
+          slotName: r.slotName,
+          persona: r.persona,
+          personaDisplay: r.personaDisplay,
+          content: typeof ((_a2 = r.pendingArm) == null ? void 0 : _a2.content) === "string" ? r.pendingArm.content : null,
+          rationale: (_b = r.rationale) != null ? _b : null,
+          refinedFrom: (_c = r.refinedFrom) != null ? _c : null,
+          updatedAt: String(r.updatedAt)
+        };
+      });
+      if (reviews.length === 0) {
+        return {
+          content: [{ type: "text", text: "No generated versions are waiting for review." }],
+          structuredContent: { reviews }
+        };
+      }
+      const lines = reviews.map(
+        (r) => [
+          `- ${untrusted(r.slotName, 60)} (slotId ${untrusted(r.slotId, 64)}) for ${untrusted(r.personaDisplay, 60)} (persona ${untrusted(r.persona, 64)})`,
+          r.content !== null ? `  Proposed text: ${untrusted(r.content, 300)}` : "  Proposed: a designed block/layout (preview it in the dashboard)",
+          r.rationale ? `  Why: ${untrusted(r.rationale, 300)}` : null,
+          r.refinedFrom ? `  Would replace ${untrusted(r.refinedFrom, 64)}, which keeps serving until approval.` : null
+        ].filter((l) => l !== null).join("\n")
+      );
+      lines.push("", "Approve or reject each with review_cell (slotId + persona) once the user has decided.");
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: { reviews } };
+    })
+  );
+  server.registerTool(
+    "review_cell",
+    {
+      title: "Approve or reject a generated version",
+      description: "Approve or reject ONE generated version waiting for review (see list_cell_reviews). 'approve' publishes it to live visitors of that type; 'reject' discards it (a rejected refinement leaves the current live version in place). This is the human decision review mode exists for \u2014 only call it with the user's explicit go-ahead.",
+      inputSchema: {
+        projectId: projectIdSchema,
+        slotId: z15.string().min(1).max(128).describe("The slot id of the version under review"),
+        persona: z15.string().min(1).max(64).describe("The persona key of the version under review"),
+        action: z15.enum(["approve", "reject"]),
+        feedback: z15.string().max(2e3).optional().describe("Optional reviewer note, stored with a rejection")
+      },
+      outputSchema: {
+        slotId: z15.string(),
+        persona: z15.string(),
+        action: z15.enum(["approve", "reject"]),
+        status: z15.string().describe("live (approved, or a rejected refinement whose incumbent keeps serving) | rejected"),
+        armId: z15.string().nullable().describe("The published option id, on approval")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId, slotId, persona, action, feedback }) => {
+      var _a, _b;
+      const id = encodeURIComponent(projectId);
+      const res = await client.post(`/projects/${id}/cells/review`, {
+        slotId,
+        persona,
+        action,
+        feedback
+      });
+      const status = (_a = res.status) != null ? _a : action === "approve" ? "live" : "rejected";
+      const text = action === "approve" ? `Approved: the version for ${untrusted(persona, 64)} in ${untrusted(slotId, 64)} is now live${res.armId ? ` as option ${untrusted(res.armId, 64)}` : ""}.` : status === "live" ? `Rejected: the proposed refinement for ${untrusted(persona, 64)} in ${untrusted(slotId, 64)} was discarded; the current live version keeps serving.` : `Rejected: the version for ${untrusted(persona, 64)} in ${untrusted(slotId, 64)} was discarded; that visitor type keeps seeing the original.`;
+      return {
+        content: [{ type: "text", text }],
+        structuredContent: { slotId, persona, action, status, armId: (_b = res.armId) != null ? _b : null }
       };
+    }, {
+      not_found: "No version is waiting for review in that cell (it may already have been approved or rejected). Check list_cell_reviews.",
+      publish_failed: "Approval could not publish this version (the slot may be full of options, or its configuration changed). It stays in review \u2014 check the reason in get_cell_detail or the dashboard, then retry."
     })
   );
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.19.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.21.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {