@sentientui/mcp 0.23.0 → 0.24.1

package/AGENTS.md

@@ -56,7 +56,7 @@ Every write tool changes what real visitors see or what the project accepts —
 | `get_funnel_report` | read | Step-by-step funnel drop-off |
 | `list_guardrail_events` | read | Every variant still paused by a guardrail; `days` narrows to recent pauses |
 | `get_persona_breakdown` | read | Cluster distribution + avg reliability per cluster (all retained sessions, not windowed) |
-| `get_stage_breakdown` | read | E-commerce funnel stages: stage mix (observed vs hinted), arrival channel x stage, raw holdout per context, versions per context with evidence (windowed, observational — nothing serves on stage yet) |
+| `get_stage_breakdown` | read | E-commerce funnel stages: stage mix (observed vs hinted), arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel (the headline lift's always-valid test, all-time, alpha split over 23 series), versions per context with evidence (windowed, observational) |
 | `get_layout_stats` | read | Per-persona layout order + bandit pulls/reward (cumulative state, not windowed) |
 | `get_insights` | read | Ranked measured findings (tier + sample, low-sample flagged; `limit`, default 10) + (Growth) AI narrations, which are unmeasured |
 | `refresh_insights` | write | Async trigger — wait ~15s then call `get_insights`. Starter+ and an editor/admin role |

package/README.md

@@ -107,7 +107,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
 | `get_funnel_report` | read | Step-by-step funnel drop-off |
 | `list_guardrail_events` | read | Every variant currently paused by a guardrail (pass `days` to see only pauses from the last N days) |
 | `get_persona_breakdown` | read | Visitor clusters with session counts and reliability (all retained sessions) |
-| `get_stage_breakdown` | read | E-commerce funnel stages: stage mix, arrival channel x stage, holdout per context and versions per context (windowed, observational) |
+| `get_stage_breakdown` | read | E-commerce funnel stages: stage mix, arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel (all-time), and versions per context (windowed, observational) |
 | `get_layout_stats` | read | Per-persona section order with bandit pulls and reward (cumulative state) |
 | `get_insights` | read | Ranked measured findings with their sample (low samples flagged), plus AI narrations marked unmeasured |
 | `refresh_insights` | write | Regenerate AI insights — needs Starter or higher and an editor/admin role (a paid model call); advisor recommendations are Growth+ |

package/dist/{chunk-P3XRXJKT.js → chunk-G6WGJ7A5.js}

@@ -1241,7 +1241,36 @@ function registerPersonaTools(server, client) {
 // src/tools/stages.ts
 import { z as z6 } from "zod";
 var pct = (v) => v == null ? "n/a (too few sessions)" : `${(v * 100).toFixed(1)}%`;
-var side = z6.object({ sessions: z6.number(), conversions: z6.number(), conversionRate: z6.number().nullable() });
+var counts = z6.object({ visitors: z6.number(), conversions: z6.number() });
+var segmentLift = z6.object({
+  key: z6.string(),
+  kind: z6.string().describe("stage | arrival | channel"),
+  evidence: z6.string().describe("collecting | awaiting_conversions | not_significant | significant_positive | significant_negative"),
+  testStarted: z6.boolean().describe("False until the series has 100 visitors per side and 10 conversions (its test scale is then fixed)"),
+  liftPct: z6.number().nullable().describe("Relative lift %, null while collecting / awaiting conversions"),
+  diffInterval: z6.object({ lower: z6.number(), upper: z6.number() }).nullable().describe("Always-valid range on the absolute rate difference (fractions)"),
+  pValue: z6.number().nullable(),
+  rates: z6.object({ adapted: z6.number(), control: z6.number() }).nullable(),
+  adapted: counts,
+  control: counts,
+  epochs: z6.number()
+});
+function liftWords(l, minPerArm) {
+  const n = `adapted ${l.adapted.visitors} / control ${l.control.visitors} visitors`;
+  switch (l.evidence) {
+    case "collecting":
+      return `early \u2014 ${n}; a number shows at ${minPerArm} per side`;
+    case "awaiting_conversions":
+      return `early \u2014 ${n}; waiting on control-group conversions`;
+    case "not_significant":
+      return `not proven yet${l.liftPct != null ? ` (${l.liftPct > 0 ? "+" : ""}${l.liftPct}%, could be chance)` : ""}${l.testStarted ? "" : " \u2014 test not started"} \u2014 ${n}`;
+    case "significant_positive":
+    case "significant_negative":
+      return `tested: ${l.liftPct != null && l.liftPct > 0 ? "+" : ""}${l.liftPct}% conversion${l.evidence === "significant_negative" ? " (worse)" : ""}${l.diffInterval ? `, range ${(l.diffInterval.lower * 100).toFixed(2)} to ${(l.diffInterval.upper * 100).toFixed(2)} pts` : ""} \u2014 ${n}`;
+    default:
+      return n;
+  }
+}
 function registerStageTools(server, client) {
   server.registerTool(
     "get_stage_breakdown",
@@ -1250,7 +1279,7 @@ function registerStageTools(server, client) {
       // Mirrors GET /projects/:id/stage-report. Says OBSERVATIONAL in the
       // description because nothing serves on stage yet: an agent must not
       // read a per-context arm result as "stage-based serving would win".
-      description: "E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of human sessions per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, holdout vs treated conversion per context (raw rates, observational \u2014 no significance test), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Returns enabled:false when the project does not record stages." + UNTRUSTED_FIELDS_NOTE,
+      description: `E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of human sessions per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, how visitors moved between stages from one visit to the next, the TESTED holdout lift per first-visit context and per first-visit arrival channel (the same always-valid test as the headline lift, all-time, alpha split over all 23 possible series; "collecting" and "awaiting_conversions" are early, not results), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Returns enabled:false when the project does not record stages.` + UNTRUSTED_FIELDS_NOTE,
       inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       outputSchema: {
         enabled: z6.boolean().describe("False when the project does not record funnel stages (settings.stage absent)"),
@@ -1263,11 +1292,29 @@ function registerStageTools(server, client) {
         contexts: z6.array(z6.object({
           context: z6.string(),
           kind: z6.string().describe("stage | arrival"),
-          sessions: z6.number(),
-          treated: side,
-          holdout: side,
-          rawLiftPct: z6.number().nullable().describe("Raw relative difference, %; null until both arms have 100 sessions. Observational.")
+          sessions: z6.number()
         })),
+        holdoutLift: z6.object({
+          basis: z6.string().describe("'first_visit': visitors grouped by their first visit's context/channel"),
+          allTime: z6.boolean().describe("True: the window does not apply to the lift"),
+          goal: z6.string(),
+          alpha: z6.number().describe("Per-series alpha after the correction"),
+          family: z6.number(),
+          minPerArm: z6.number(),
+          units: z6.number(),
+          unclassified: z6.number().describe("Exposed visitors with no first-visit record (exposed before recording began)"),
+          contexts: z6.array(segmentLift),
+          channels: z6.array(segmentLift)
+        }).nullable().optional(),
+        transitions: z6.object({
+          pairs: z6.number().describe("Consecutive recorded visits in the window"),
+          visitors: z6.number(),
+          rows: z6.array(z6.object({
+            from: z6.string(),
+            nextVisits: z6.number(),
+            to: z6.array(z6.object({ stage: z6.string(), visits: z6.number(), visitors: z6.number(), share: z6.number().describe("0-1") }))
+          }))
+        }).optional(),
         arms: z6.array(z6.object({
           slotId: z6.string(),
           slotName: z6.string(),
@@ -1285,6 +1332,7 @@ function registerStageTools(server, client) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, range, from, to }) => {
+      var _a;
       const id = encodeURIComponent(projectId);
       const r = await client.get(`/projects/${id}/stage-report${rangeQuery({ range, from, to })}`);
       const structuredContent = {
@@ -1296,6 +1344,8 @@ function registerStageTools(server, client) {
         channels: r.channels,
         arrivals: r.arrivals,
         contexts: r.contexts,
+        holdoutLift: (_a = r.holdoutLift) != null ? _a : null,
+        transitions: r.transitions,
         arms: r.arms,
         window: r.window
       };
@@ -1320,11 +1370,24 @@ function registerStageTools(server, client) {
         ...r.stages.map((s) => `- ${s.stage}: ${s.sessions} (${(s.share * 100).toFixed(1)}%)${s.hinted ? `, ${s.hinted} hinted` : ""}`),
         "",
         "Arrival channel x stage (conversion):",
-        ...r.arrivals.map((a) => `- ${a.channel} / ${a.stage}: ${a.sessions} sessions, ${pct(a.conversionRate)}`),
-        "",
-        "Holdout vs treated per context (raw rates, no significance test):",
-        ...r.contexts.filter((c) => c.sessions > 0).map((c) => `- ${c.context}: treated ${pct(c.treated.conversionRate)} (n=${c.treated.sessions}), holdout ${pct(c.holdout.conversionRate)} (n=${c.holdout.sessions})${c.rawLiftPct != null ? `, raw difference ${c.rawLiftPct > 0 ? "+" : ""}${c.rawLiftPct}%` : ""}`)
+        ...r.arrivals.map((a) => `- ${a.channel} / ${a.stage}: ${a.sessions} sessions, ${pct(a.conversionRate)}`)
       ];
+      const t = r.transitions;
+      if (t && t.rows.length > 0) {
+        lines.push("", `Stage moves between visits (${t.pairs} next visits from ${t.visitors} returning visitors in the window):`);
+        for (const row of t.rows) {
+          lines.push(`- from ${row.from} (${row.nextVisits} next visits): ${row.to.map((x) => `${x.stage} ${(x.share * 100).toFixed(0)}%`).join(", ")}`);
+        }
+      }
+      const h = r.holdoutLift;
+      if (h && (h.contexts.length > 0 || h.channels.length > 0)) {
+        lines.push(
+          "",
+          `Holdout lift by first-visit context and channel (tested, all-time \u2014 the window does not apply; alpha ${h.alpha.toPrecision(2)} per series over ${h.family}; ${h.unclassified} of ${h.units} visitors predate recording and are not in any row):`,
+          ...h.contexts.map((l) => `- context ${l.key}: ${liftWords(l, h.minPerArm)}`),
+          ...h.channels.map((l) => `- channel ${l.key}: ${liftWords(l, h.minPerArm)}`)
+        );
+      }
       if (r.arms.length > 0) {
         lines.push("", "Versions per context (what stage-based serving would have to beat):");
         for (const a of r.arms) {
@@ -1841,7 +1904,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. 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.",
+      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. On a component that has moved to the shared track, the text is added to the component's versions instead (still a draft until activated), and text is required there (an empty create is refused); the call and its result are otherwise the same.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: z11.string().min(1).max(200).describe("The component ID to add a variant to"),
@@ -1960,7 +2023,7 @@ function registerVariantWriteTools(server, client) {
     "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.",
+      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. On a component that has moved to the shared track (one experiment with its versions), the text is edited on that component's version instead; the call and its result are the same.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: z11.string().min(1).max(200).describe("The component ID"),
@@ -2629,7 +2692,8 @@ and then, in the same tag after the ';', runs the inline pre-paint script; then
 loader. The pre-paint script reads window.sentient when it runs, so sharing the tag is safe. It
 is optional but recommended \u2014 the loader is deferred, so on a return visit the page can paint
 its original state before the loader runs; the inline script applies the last served decision
-from the visitor's own device first, with no network call and no cloak. Get the exact bytes from
+from the visitor's own device first, with no network call and no page-wide cloak (it briefly hides
+only published components, and only for a visitor who just clicked an ad or email). Get the exact bytes from
 the dashboard's Install page, or from renderSnippetInstall({ config }) in
 '@sentientui/snippet/install' (renderSnippetPrePaintScript() for the script alone).
 
@@ -3126,7 +3190,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.23.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.24.1" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {

package/dist/index.cjs

@@ -1245,7 +1245,36 @@ function registerPersonaTools(server, client) {
 // src/tools/stages.ts
 var import_zod6 = require("zod");
 var pct = (v) => v == null ? "n/a (too few sessions)" : `${(v * 100).toFixed(1)}%`;
-var side = import_zod6.z.object({ sessions: import_zod6.z.number(), conversions: import_zod6.z.number(), conversionRate: import_zod6.z.number().nullable() });
+var counts = import_zod6.z.object({ visitors: import_zod6.z.number(), conversions: import_zod6.z.number() });
+var segmentLift = import_zod6.z.object({
+  key: import_zod6.z.string(),
+  kind: import_zod6.z.string().describe("stage | arrival | channel"),
+  evidence: import_zod6.z.string().describe("collecting | awaiting_conversions | not_significant | significant_positive | significant_negative"),
+  testStarted: import_zod6.z.boolean().describe("False until the series has 100 visitors per side and 10 conversions (its test scale is then fixed)"),
+  liftPct: import_zod6.z.number().nullable().describe("Relative lift %, null while collecting / awaiting conversions"),
+  diffInterval: import_zod6.z.object({ lower: import_zod6.z.number(), upper: import_zod6.z.number() }).nullable().describe("Always-valid range on the absolute rate difference (fractions)"),
+  pValue: import_zod6.z.number().nullable(),
+  rates: import_zod6.z.object({ adapted: import_zod6.z.number(), control: import_zod6.z.number() }).nullable(),
+  adapted: counts,
+  control: counts,
+  epochs: import_zod6.z.number()
+});
+function liftWords(l, minPerArm) {
+  const n = `adapted ${l.adapted.visitors} / control ${l.control.visitors} visitors`;
+  switch (l.evidence) {
+    case "collecting":
+      return `early \u2014 ${n}; a number shows at ${minPerArm} per side`;
+    case "awaiting_conversions":
+      return `early \u2014 ${n}; waiting on control-group conversions`;
+    case "not_significant":
+      return `not proven yet${l.liftPct != null ? ` (${l.liftPct > 0 ? "+" : ""}${l.liftPct}%, could be chance)` : ""}${l.testStarted ? "" : " \u2014 test not started"} \u2014 ${n}`;
+    case "significant_positive":
+    case "significant_negative":
+      return `tested: ${l.liftPct != null && l.liftPct > 0 ? "+" : ""}${l.liftPct}% conversion${l.evidence === "significant_negative" ? " (worse)" : ""}${l.diffInterval ? `, range ${(l.diffInterval.lower * 100).toFixed(2)} to ${(l.diffInterval.upper * 100).toFixed(2)} pts` : ""} \u2014 ${n}`;
+    default:
+      return n;
+  }
+}
 function registerStageTools(server, client) {
   server.registerTool(
     "get_stage_breakdown",
@@ -1254,7 +1283,7 @@ function registerStageTools(server, client) {
       // Mirrors GET /projects/:id/stage-report. Says OBSERVATIONAL in the
       // description because nothing serves on stage yet: an agent must not
       // read a per-context arm result as "stage-based serving would win".
-      description: "E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of human sessions per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, holdout vs treated conversion per context (raw rates, observational \u2014 no significance test), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Returns enabled:false when the project does not record stages." + UNTRUSTED_FIELDS_NOTE,
+      description: `E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of human sessions per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, how visitors moved between stages from one visit to the next, the TESTED holdout lift per first-visit context and per first-visit arrival channel (the same always-valid test as the headline lift, all-time, alpha split over all 23 possible series; "collecting" and "awaiting_conversions" are early, not results), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Returns enabled:false when the project does not record stages.` + UNTRUSTED_FIELDS_NOTE,
       inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       outputSchema: {
         enabled: import_zod6.z.boolean().describe("False when the project does not record funnel stages (settings.stage absent)"),
@@ -1267,11 +1296,29 @@ function registerStageTools(server, client) {
         contexts: import_zod6.z.array(import_zod6.z.object({
           context: import_zod6.z.string(),
           kind: import_zod6.z.string().describe("stage | arrival"),
-          sessions: import_zod6.z.number(),
-          treated: side,
-          holdout: side,
-          rawLiftPct: import_zod6.z.number().nullable().describe("Raw relative difference, %; null until both arms have 100 sessions. Observational.")
+          sessions: import_zod6.z.number()
         })),
+        holdoutLift: import_zod6.z.object({
+          basis: import_zod6.z.string().describe("'first_visit': visitors grouped by their first visit's context/channel"),
+          allTime: import_zod6.z.boolean().describe("True: the window does not apply to the lift"),
+          goal: import_zod6.z.string(),
+          alpha: import_zod6.z.number().describe("Per-series alpha after the correction"),
+          family: import_zod6.z.number(),
+          minPerArm: import_zod6.z.number(),
+          units: import_zod6.z.number(),
+          unclassified: import_zod6.z.number().describe("Exposed visitors with no first-visit record (exposed before recording began)"),
+          contexts: import_zod6.z.array(segmentLift),
+          channels: import_zod6.z.array(segmentLift)
+        }).nullable().optional(),
+        transitions: import_zod6.z.object({
+          pairs: import_zod6.z.number().describe("Consecutive recorded visits in the window"),
+          visitors: import_zod6.z.number(),
+          rows: import_zod6.z.array(import_zod6.z.object({
+            from: import_zod6.z.string(),
+            nextVisits: import_zod6.z.number(),
+            to: import_zod6.z.array(import_zod6.z.object({ stage: import_zod6.z.string(), visits: import_zod6.z.number(), visitors: import_zod6.z.number(), share: import_zod6.z.number().describe("0-1") }))
+          }))
+        }).optional(),
         arms: import_zod6.z.array(import_zod6.z.object({
           slotId: import_zod6.z.string(),
           slotName: import_zod6.z.string(),
@@ -1289,6 +1336,7 @@ function registerStageTools(server, client) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, range, from, to }) => {
+      var _a2;
       const id = encodeURIComponent(projectId);
       const r = await client.get(`/projects/${id}/stage-report${rangeQuery({ range, from, to })}`);
       const structuredContent = {
@@ -1300,6 +1348,8 @@ function registerStageTools(server, client) {
         channels: r.channels,
         arrivals: r.arrivals,
         contexts: r.contexts,
+        holdoutLift: (_a2 = r.holdoutLift) != null ? _a2 : null,
+        transitions: r.transitions,
         arms: r.arms,
         window: r.window
       };
@@ -1324,11 +1374,24 @@ function registerStageTools(server, client) {
         ...r.stages.map((s) => `- ${s.stage}: ${s.sessions} (${(s.share * 100).toFixed(1)}%)${s.hinted ? `, ${s.hinted} hinted` : ""}`),
         "",
         "Arrival channel x stage (conversion):",
-        ...r.arrivals.map((a) => `- ${a.channel} / ${a.stage}: ${a.sessions} sessions, ${pct(a.conversionRate)}`),
-        "",
-        "Holdout vs treated per context (raw rates, no significance test):",
-        ...r.contexts.filter((c) => c.sessions > 0).map((c) => `- ${c.context}: treated ${pct(c.treated.conversionRate)} (n=${c.treated.sessions}), holdout ${pct(c.holdout.conversionRate)} (n=${c.holdout.sessions})${c.rawLiftPct != null ? `, raw difference ${c.rawLiftPct > 0 ? "+" : ""}${c.rawLiftPct}%` : ""}`)
+        ...r.arrivals.map((a) => `- ${a.channel} / ${a.stage}: ${a.sessions} sessions, ${pct(a.conversionRate)}`)
       ];
+      const t = r.transitions;
+      if (t && t.rows.length > 0) {
+        lines.push("", `Stage moves between visits (${t.pairs} next visits from ${t.visitors} returning visitors in the window):`);
+        for (const row of t.rows) {
+          lines.push(`- from ${row.from} (${row.nextVisits} next visits): ${row.to.map((x) => `${x.stage} ${(x.share * 100).toFixed(0)}%`).join(", ")}`);
+        }
+      }
+      const h = r.holdoutLift;
+      if (h && (h.contexts.length > 0 || h.channels.length > 0)) {
+        lines.push(
+          "",
+          `Holdout lift by first-visit context and channel (tested, all-time \u2014 the window does not apply; alpha ${h.alpha.toPrecision(2)} per series over ${h.family}; ${h.unclassified} of ${h.units} visitors predate recording and are not in any row):`,
+          ...h.contexts.map((l) => `- context ${l.key}: ${liftWords(l, h.minPerArm)}`),
+          ...h.channels.map((l) => `- channel ${l.key}: ${liftWords(l, h.minPerArm)}`)
+        );
+      }
       if (r.arms.length > 0) {
         lines.push("", "Versions per context (what stage-based serving would have to beat):");
         for (const a of r.arms) {
@@ -1845,7 +1908,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. 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.",
+      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. On a component that has moved to the shared track, the text is added to the component's versions instead (still a draft until activated), and text is required there (an empty create is refused); the call and its result are otherwise the same.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: import_zod11.z.string().min(1).max(200).describe("The component ID to add a variant to"),
@@ -1964,7 +2027,7 @@ function registerVariantWriteTools(server, client) {
     "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.",
+      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. On a component that has moved to the shared track (one experiment with its versions), the text is edited on that component's version instead; the call and its result are the same.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: import_zod11.z.string().min(1).max(200).describe("The component ID"),
@@ -2633,7 +2696,8 @@ and then, in the same tag after the ';', runs the inline pre-paint script; then
 loader. The pre-paint script reads window.sentient when it runs, so sharing the tag is safe. It
 is optional but recommended \u2014 the loader is deferred, so on a return visit the page can paint
 its original state before the loader runs; the inline script applies the last served decision
-from the visitor's own device first, with no network call and no cloak. Get the exact bytes from
+from the visitor's own device first, with no network call and no page-wide cloak (it briefly hides
+only published components, and only for a visitor who just clicked an ad or email). Get the exact bytes from
 the dashboard's Install page, or from renderSnippetInstall({ config }) in
 '@sentientui/snippet/install' (renderSnippetPrePaintScript() for the script alone).
 
@@ -3130,7 +3194,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.23.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.24.1" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   ApiClient,
   createMcpServer
-} from "./chunk-P3XRXJKT.js";
+} from "./chunk-G6WGJ7A5.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -1271,7 +1271,36 @@ function registerPersonaTools(server, client) {
 // src/tools/stages.ts
 var import_zod6 = require("zod");
 var pct = (v) => v == null ? "n/a (too few sessions)" : `${(v * 100).toFixed(1)}%`;
-var side = import_zod6.z.object({ sessions: import_zod6.z.number(), conversions: import_zod6.z.number(), conversionRate: import_zod6.z.number().nullable() });
+var counts = import_zod6.z.object({ visitors: import_zod6.z.number(), conversions: import_zod6.z.number() });
+var segmentLift = import_zod6.z.object({
+  key: import_zod6.z.string(),
+  kind: import_zod6.z.string().describe("stage | arrival | channel"),
+  evidence: import_zod6.z.string().describe("collecting | awaiting_conversions | not_significant | significant_positive | significant_negative"),
+  testStarted: import_zod6.z.boolean().describe("False until the series has 100 visitors per side and 10 conversions (its test scale is then fixed)"),
+  liftPct: import_zod6.z.number().nullable().describe("Relative lift %, null while collecting / awaiting conversions"),
+  diffInterval: import_zod6.z.object({ lower: import_zod6.z.number(), upper: import_zod6.z.number() }).nullable().describe("Always-valid range on the absolute rate difference (fractions)"),
+  pValue: import_zod6.z.number().nullable(),
+  rates: import_zod6.z.object({ adapted: import_zod6.z.number(), control: import_zod6.z.number() }).nullable(),
+  adapted: counts,
+  control: counts,
+  epochs: import_zod6.z.number()
+});
+function liftWords(l, minPerArm) {
+  const n = `adapted ${l.adapted.visitors} / control ${l.control.visitors} visitors`;
+  switch (l.evidence) {
+    case "collecting":
+      return `early \u2014 ${n}; a number shows at ${minPerArm} per side`;
+    case "awaiting_conversions":
+      return `early \u2014 ${n}; waiting on control-group conversions`;
+    case "not_significant":
+      return `not proven yet${l.liftPct != null ? ` (${l.liftPct > 0 ? "+" : ""}${l.liftPct}%, could be chance)` : ""}${l.testStarted ? "" : " \u2014 test not started"} \u2014 ${n}`;
+    case "significant_positive":
+    case "significant_negative":
+      return `tested: ${l.liftPct != null && l.liftPct > 0 ? "+" : ""}${l.liftPct}% conversion${l.evidence === "significant_negative" ? " (worse)" : ""}${l.diffInterval ? `, range ${(l.diffInterval.lower * 100).toFixed(2)} to ${(l.diffInterval.upper * 100).toFixed(2)} pts` : ""} \u2014 ${n}`;
+    default:
+      return n;
+  }
+}
 function registerStageTools(server, client) {
   server.registerTool(
     "get_stage_breakdown",
@@ -1280,7 +1309,7 @@ function registerStageTools(server, client) {
       // Mirrors GET /projects/:id/stage-report. Says OBSERVATIONAL in the
       // description because nothing serves on stage yet: an agent must not
       // read a per-context arm result as "stage-based serving would win".
-      description: "E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of human sessions per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, holdout vs treated conversion per context (raw rates, observational \u2014 no significance test), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Returns enabled:false when the project does not record stages." + UNTRUSTED_FIELDS_NOTE,
+      description: `E-commerce projects: where visitors are in buying (new, browsing, carted, customer, lapsed) \u2014 share of human sessions per stage (each session counted once, at its latest recorded stage; hinted = set by a tagged campaign, not observed history), arrival channel x stage with conversion, how visitors moved between stages from one visit to the next, the TESTED holdout lift per first-visit context and per first-visit arrival channel (the same always-valid test as the headline lift, all-time, alpha split over all 23 possible series; "collecting" and "awaiting_conversions" are early, not results), and each region's versions per context judged against the original with the per-audience evidence rule. OBSERVATIONAL: nothing is served by stage yet; the per-context results are what stage-based serving would have to beat. Defaults to the last 30 days; pass range or from/to. Returns enabled:false when the project does not record stages.` + UNTRUSTED_FIELDS_NOTE,
       inputSchema: __spreadValues({ projectId: projectIdSchema }, rangeInputSchema("30d")),
       outputSchema: {
         enabled: import_zod6.z.boolean().describe("False when the project does not record funnel stages (settings.stage absent)"),
@@ -1293,11 +1322,29 @@ function registerStageTools(server, client) {
         contexts: import_zod6.z.array(import_zod6.z.object({
           context: import_zod6.z.string(),
           kind: import_zod6.z.string().describe("stage | arrival"),
-          sessions: import_zod6.z.number(),
-          treated: side,
-          holdout: side,
-          rawLiftPct: import_zod6.z.number().nullable().describe("Raw relative difference, %; null until both arms have 100 sessions. Observational.")
+          sessions: import_zod6.z.number()
         })),
+        holdoutLift: import_zod6.z.object({
+          basis: import_zod6.z.string().describe("'first_visit': visitors grouped by their first visit's context/channel"),
+          allTime: import_zod6.z.boolean().describe("True: the window does not apply to the lift"),
+          goal: import_zod6.z.string(),
+          alpha: import_zod6.z.number().describe("Per-series alpha after the correction"),
+          family: import_zod6.z.number(),
+          minPerArm: import_zod6.z.number(),
+          units: import_zod6.z.number(),
+          unclassified: import_zod6.z.number().describe("Exposed visitors with no first-visit record (exposed before recording began)"),
+          contexts: import_zod6.z.array(segmentLift),
+          channels: import_zod6.z.array(segmentLift)
+        }).nullable().optional(),
+        transitions: import_zod6.z.object({
+          pairs: import_zod6.z.number().describe("Consecutive recorded visits in the window"),
+          visitors: import_zod6.z.number(),
+          rows: import_zod6.z.array(import_zod6.z.object({
+            from: import_zod6.z.string(),
+            nextVisits: import_zod6.z.number(),
+            to: import_zod6.z.array(import_zod6.z.object({ stage: import_zod6.z.string(), visits: import_zod6.z.number(), visitors: import_zod6.z.number(), share: import_zod6.z.number().describe("0-1") }))
+          }))
+        }).optional(),
         arms: import_zod6.z.array(import_zod6.z.object({
           slotId: import_zod6.z.string(),
           slotName: import_zod6.z.string(),
@@ -1315,6 +1362,7 @@ function registerStageTools(server, client) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, range, from, to }) => {
+      var _a;
       const id = encodeURIComponent(projectId);
       const r = await client.get(`/projects/${id}/stage-report${rangeQuery({ range, from, to })}`);
       const structuredContent = {
@@ -1326,6 +1374,8 @@ function registerStageTools(server, client) {
         channels: r.channels,
         arrivals: r.arrivals,
         contexts: r.contexts,
+        holdoutLift: (_a = r.holdoutLift) != null ? _a : null,
+        transitions: r.transitions,
         arms: r.arms,
         window: r.window
       };
@@ -1350,11 +1400,24 @@ function registerStageTools(server, client) {
         ...r.stages.map((s) => `- ${s.stage}: ${s.sessions} (${(s.share * 100).toFixed(1)}%)${s.hinted ? `, ${s.hinted} hinted` : ""}`),
         "",
         "Arrival channel x stage (conversion):",
-        ...r.arrivals.map((a) => `- ${a.channel} / ${a.stage}: ${a.sessions} sessions, ${pct(a.conversionRate)}`),
-        "",
-        "Holdout vs treated per context (raw rates, no significance test):",
-        ...r.contexts.filter((c) => c.sessions > 0).map((c) => `- ${c.context}: treated ${pct(c.treated.conversionRate)} (n=${c.treated.sessions}), holdout ${pct(c.holdout.conversionRate)} (n=${c.holdout.sessions})${c.rawLiftPct != null ? `, raw difference ${c.rawLiftPct > 0 ? "+" : ""}${c.rawLiftPct}%` : ""}`)
+        ...r.arrivals.map((a) => `- ${a.channel} / ${a.stage}: ${a.sessions} sessions, ${pct(a.conversionRate)}`)
       ];
+      const t = r.transitions;
+      if (t && t.rows.length > 0) {
+        lines.push("", `Stage moves between visits (${t.pairs} next visits from ${t.visitors} returning visitors in the window):`);
+        for (const row of t.rows) {
+          lines.push(`- from ${row.from} (${row.nextVisits} next visits): ${row.to.map((x) => `${x.stage} ${(x.share * 100).toFixed(0)}%`).join(", ")}`);
+        }
+      }
+      const h = r.holdoutLift;
+      if (h && (h.contexts.length > 0 || h.channels.length > 0)) {
+        lines.push(
+          "",
+          `Holdout lift by first-visit context and channel (tested, all-time \u2014 the window does not apply; alpha ${h.alpha.toPrecision(2)} per series over ${h.family}; ${h.unclassified} of ${h.units} visitors predate recording and are not in any row):`,
+          ...h.contexts.map((l) => `- context ${l.key}: ${liftWords(l, h.minPerArm)}`),
+          ...h.channels.map((l) => `- channel ${l.key}: ${liftWords(l, h.minPerArm)}`)
+        );
+      }
       if (r.arms.length > 0) {
         lines.push("", "Versions per context (what stage-based serving would have to beat):");
         for (const a of r.arms) {
@@ -1871,7 +1934,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. 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.",
+      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. On a component that has moved to the shared track, the text is added to the component's versions instead (still a draft until activated), and text is required there (an empty create is refused); the call and its result are otherwise the same.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: import_zod11.z.string().min(1).max(200).describe("The component ID to add a variant to"),
@@ -1990,7 +2053,7 @@ function registerVariantWriteTools(server, client) {
     "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.",
+      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. On a component that has moved to the shared track (one experiment with its versions), the text is edited on that component's version instead; the call and its result are the same.",
       inputSchema: {
         projectId: projectIdSchema,
         componentId: import_zod11.z.string().min(1).max(200).describe("The component ID"),
@@ -2659,7 +2722,8 @@ and then, in the same tag after the ';', runs the inline pre-paint script; then
 loader. The pre-paint script reads window.sentient when it runs, so sharing the tag is safe. It
 is optional but recommended \u2014 the loader is deferred, so on a return visit the page can paint
 its original state before the loader runs; the inline script applies the last served decision
-from the visitor's own device first, with no network call and no cloak. Get the exact bytes from
+from the visitor's own device first, with no network call and no page-wide cloak (it briefly hides
+only published components, and only for a visitor who just clicked an ad or email). Get the exact bytes from
 the dashboard's Install page, or from renderSnippetInstall({ config }) in
 '@sentientui/snippet/install' (renderSnippetPrePaintScript() for the script alone).
 
@@ -3156,7 +3220,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.23.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.24.1" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -3224,7 +3288,7 @@ var TOOL_CATALOG = [
   { name: "list_guardrail_events", access: "read", summary: "Every variant currently paused by a guardrail (optionally only pauses from the last N days)" },
   // Audience and layout
   { name: "get_persona_breakdown", access: "read", summary: "Visitor clusters with session counts and reliability (all retained sessions)" },
-  { name: "get_stage_breakdown", access: "read", summary: "E-commerce funnel stages: stage mix, arrival channel x stage, holdout per context and versions per context (windowed, observational)" },
+  { name: "get_stage_breakdown", access: "read", summary: "E-commerce funnel stages: stage mix, arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel, and versions per context (windowed, observational)" },
   { name: "get_layout_stats", access: "read", summary: "Per-persona section order with bandit pulls and reward (cumulative state)" },
   // Insights
   { name: "get_insights", access: "read", summary: "Ranked measured findings with their sample, plus AI narrations marked unmeasured" },

package/dist/lib.js

@@ -4,7 +4,7 @@ import {
   ApiError,
   PUBLIC_UI_RESOURCE_URIS,
   createMcpServer
-} from "./chunk-P3XRXJKT.js";
+} from "./chunk-G6WGJ7A5.js";
 
 // src/tool-catalog.ts
 var TOOL_CATALOG = [
@@ -34,7 +34,7 @@ var TOOL_CATALOG = [
   { name: "list_guardrail_events", access: "read", summary: "Every variant currently paused by a guardrail (optionally only pauses from the last N days)" },
   // Audience and layout
   { name: "get_persona_breakdown", access: "read", summary: "Visitor clusters with session counts and reliability (all retained sessions)" },
-  { name: "get_stage_breakdown", access: "read", summary: "E-commerce funnel stages: stage mix, arrival channel x stage, holdout per context and versions per context (windowed, observational)" },
+  { name: "get_stage_breakdown", access: "read", summary: "E-commerce funnel stages: stage mix, arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel, and versions per context (windowed, observational)" },
   { name: "get_layout_stats", access: "read", summary: "Per-persona section order with bandit pulls and reward (cumulative state)" },
   // Insights
   { name: "get_insights", access: "read", summary: "Ranked measured findings with their sample, plus AI narrations marked unmeasured" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "license": "MIT",
   "homepage": "https://sentient-ui.com",