@sentientui/mcp 0.18.0 → 0.18.2

package/README.md

@@ -105,6 +105,8 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, read-onl
 | `get_cell_detail` | One cell's story: the generated option, why it was written (stored rationale), and how it performs vs the original |
 | `generate_cell` | Queue AI generation of a version for one (visitor type, region) cell — brand-locked, live in under a minute (paid plan) |
 
+> **Generated versions.** An `<Adaptive id="…">` that wraps your original as children (no `variants`) registers as a personalizable region once it is mounted and deployed. Its versions per visitor type are written in SentientUI — inspect and fill them with `get_cell_matrix`, `get_cell_detail`, and `generate_cell` — with no code change or redeploy.
+>
 > **Code-native vs no-code variants.** Variants you declare in your app (`<Adaptive variants={{…}}>`) register automatically the first time the SDK requests an assignment after you deploy — they go live immediately and need **no** `create_variant` call. Use `create_variant` only for **no-code** variants whose content is stored in SentientUI and rendered without a code change; these start as drafts you activate from the dashboard.
 >
 > **Optimizing a component?** Call `get_variant_brief` first. It returns the component's performance, audience, insights, and a data-sufficiency assessment — then your AI assistant writes a new on-brand variant directly into your code (which auto-registers on deploy). When there's no data yet, the brief falls back to best-practice priors for your project's context type so the assistant still makes a sensible change.

package/dist/{chunk-PX6RCSB2.js → chunk-5TEQLWMW.js}

@@ -1789,8 +1789,9 @@ import { z as z13 } from "zod";
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas), learning from real conversions. Each
-project has its own persona vocabulary (dashboard -> Settings -> Personas; the default is
-buyer, researcher, deal_seeker, browser + unknown). Personas are inferred from behavior \u2014 or
+project has its own persona vocabulary (dashboard -> Settings -> Personas), and it starts
+EMPTY: every visitor is 'unknown' until a persona exists, and the optimizer learns across all
+traffic pooled in the meantime. Personas are DISCOVERED from behavior \u2014 or, far faster,
 DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
 <AdaptiveProvider persona=...> / window.sentient.persona. Declared beats inferred and serves
 at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
@@ -1803,12 +1804,14 @@ time.
 1. Run \`npx @sentientui/cli init\` (detects Next App/Pages, Vite, Remix, CRA; installs
    @sentientui/react; writes .env.local; scaffolds an example). It does NOT edit your layout \u2014
    it prints the wrap snippet for step 2.
-2. Wrap the root layout with <AdaptiveRoot apiKey context> (from '@sentientui/react/next';
-   other React apps use <AdaptiveProvider> from '@sentientui/react') and add
-   suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes pre-paint.
-   Nothing adapts and nothing is tracked until this wrap is in place.
-3. \`npm run dev\`, then open the app with \`?sentient_persona=buyer\` vs
-   \`?sentient_persona=deal_seeker\` to see it adapt. No API key needed (keyless local mode).
+2. Wrap the root layout with <AdaptiveRoot apiKey>{children}</AdaptiveRoot> (from
+   '@sentientui/react/next'; other React apps use <AdaptiveProvider> from '@sentientui/react')
+   and add suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes
+   pre-paint. Nothing adapts and nothing is tracked until this wrap is in place. Declare no
+   components here: every <Adaptive> registers itself when it renders (see Rung 2).
+3. \`npm run dev\`, then open the app with \`?sentient_persona=a\` vs
+   \`?sentient_persona=b\` to see it adapt \u2014 in keyless local mode any key drives the built-in
+   heuristic. No API key needed. Against a real project the key must be one you declared.
 4. To learn from real traffic: create a project at https://sentient-ui.com and set
    NEXT_PUBLIC_SENTIENT_API_KEY=pk_... in .env.local.
 
@@ -1817,8 +1820,8 @@ time.
 Persona attributes on <html> (zero declaration; the attribute carries the project's own
 vocabulary keys \u2014 declared or inferred):
 
-    html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
-    html[data-sentient-confidence='low'] .discount-banner { display: none; }
+    html[data-sentient-persona='admin'] .admin-tools { display: block; }
+    html[data-sentient-confidence='low'] .admin-tools { display: none; }
 
 Learned style tokens (element-scoped, SSR-safe):
 
@@ -1833,14 +1836,43 @@ prefers-reduced-motion: reduce override in CSS.
 
 ## Rung 2 \u2014 Swap (alternate content)
 
+Generated versions (start here) \u2014 wrap what the page shows today; the children are the
+original:
+
+    <Adaptive id="hero-cta" goal="signup_click">
+      <a href="/signup">Start free trial</a>
+    </Adaptive>
+
+Mount + deploy registers the region. SentientUI writes versions per visitor type in the
+dashboard ("Who sees what") \u2014 no redeploy. The children render for holdout traffic, unknown
+visitor types, types with no version yet, and every error path. Mounted regions are requested
+in one batched call after mount: the first visit shows the original briefly, then swaps; return
+visits start from the last version. Keyless local mode renders originals only.
+
+Optional server preload (Next.js App Router): registrySlotIds={['hero-cta']} for generated
+regions, components={[{ id, variantIds }]} for code variants, both on AdaptiveRoot \u2014 the first
+paint then shows the served version. List ONLY ids rendered on every page that AdaptiveRoot
+wraps (in app/layout.tsx, every route): a declared id is decided on every request, rendered or
+not, and those visits count as views that can never convert.
+
+Pass
+onFormSubmit to allow form versions; set reportBaselineText={false} on regions wrapping
+personalized or account content. (Formerly <AdaptiveSlot>.)
+
+Code variants \u2014 when you write the alternatives yourself:
+
+    <Adaptive id="buy-box" goal="buy_click"                      // goal REQUIRED
+      variants={{ control: <CalmBuyBox/>, urgent: <UrgentBuyBox/> }} />  // first key = baseline
+
+    // hook form:
     const { value, bind } = useAdaptive('buy-box', {
       variants: { calm: <CalmBuyBox/>, urgent: <UrgentBuyBox/> },  // first key = baseline
       goal: 'buy_click',                                            // REQUIRED
     });
     return <div {...bind}>{value}</div>;
 
-Always attach bind \u2014 it wires exposure tracking and goal listeners. <Adaptive> is the wrapper
-form; <AdaptiveText> swaps dashboard-managed text.
+Children or variants on one <Adaptive>, never both. With the hook, always attach bind \u2014 it
+wires exposure tracking and goal listeners. <AdaptiveText> swaps dashboard-managed text.
 
 ## Rung 3 \u2014 Reorder (structure)
 
@@ -1858,12 +1890,20 @@ their shared parent, and applies nothing if any selector drifts.
 
 ## No-code install order (snippet)
 
-Three tags in <head>, in this order: the window.sentient config, the inline pre-paint script,
-then the deferred loader. The middle tag 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 its exact bytes from the dashboard's Install page, or from
-renderSnippetPrePaintScript() in '@sentientui/snippet/install'.
+Two tags in <head>, in this order: one inline <script> that assigns the window.sentient config
+and then, in the same tag after the ';', runs the inline pre-paint script; then the deferred
+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
+the dashboard's Install page, or from renderSnippetInstall({ config }) in
+'@sentientui/snippet/install' (renderSnippetPrePaintScript() for the script alone).
+
+Strict Content-Security-Policy (script hashes): use the three-tag form instead \u2014 config, the
+pre-paint script alone, then the loader (renderSnippetInstall({ config, split: true })). The
+combined tag contains the site's config, so its hash differs per site; the split pre-paint tag is
+byte-identical everywhere, so one hash covers it. Existing three-tag and config + loader installs
+keep working.
 
 ## Testing the integration
 
@@ -2043,12 +2083,17 @@ var cellOutput = z15.object({
   rationale: z15.string().nullable(),
   error: z15.string().nullable(),
   updatedAt: z15.string(),
+  // These ride the API response too; omitting them from the schema made zod
+  // STRIP them, so agents could never see refinement or retry state.
+  refinedFrom: z15.string().nullable().optional().describe("Incumbent arm this cell is improving on \u2014 a pending cell with this set still SERVES the incumbent"),
+  notBefore: z15.string().nullable().optional().describe("ISO time the queue will next consider this cell (retry backoff / daily-cap deferral); null when due now"),
+  attempts: z15.number().optional().describe("Generation attempts so far"),
   performance: z15.object({
     shown: z15.number(),
     conversions: z15.number(),
     deltaPct: z15.number().nullable().describe("Signed % vs the original conversion rate"),
     tier: z15.string().describe("early | no_baseline | winning | losing | flat")
-  }).optional().describe("Present on live cells: the at-a-glance readout")
+  }).optional().describe("Present on live cells (and, mid-refinement, the incumbent arm): the at-a-glance readout")
 });
 function registerCellTools(server, client) {
   server.registerTool(
@@ -2058,7 +2103,15 @@ function registerCellTools(server, client) {
       description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        slots: z15.array(z15.object({ slotId: z15.string(), displayName: z15.string(), supportsForms: z15.boolean() })),
+        slots: z15.array(
+          z15.object({
+            slotId: z15.string(),
+            displayName: z15.string(),
+            supportsForms: z15.boolean(),
+            // API sends this; without it zod stripped the draft-vs-live signal.
+            live: z15.boolean().optional().describe("False for an sdk-registered draft column \u2014 nothing serves until its first generation publishes it")
+          })
+        ),
         personas: z15.array(personaOutput),
         cells: z15.array(cellOutput),
         autoFill: z15.boolean(),
@@ -2072,13 +2125,19 @@ function registerCellTools(server, client) {
       const data = await client.get(`/projects/${id}/cells`);
       const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
       const lines = [
-        `Slots: ${data.slots.map((s) => untrusted(s.displayName)).join(", ") || "(none published)"}`,
+        `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: ${data.personaSource}`
       ];
       for (const p of data.personas) {
         const states = data.slots.map((s) => {
           const c = byCell.get(`${s.slotId}::${p.key}`);
-          return `${untrusted(s.displayName, 40)}: ${c ? c.status : "original"}`;
+          let state = c ? c.status : "original";
+          if (c && (c.status === "pending" || c.status === "generating") && c.refinedFrom) {
+            state = `${c.status} (improving on ${untrusted(c.refinedFrom, 64)} \u2014 current version still live)`;
+          } else if (c && c.status === "pending" && c.notBefore && Date.parse(c.notBefore) > Date.now()) {
+            state = `pending (waiting until ${c.notBefore})`;
+          }
+          return `${untrusted(s.displayName, 40)}: ${state}`;
         });
         lines.push(`- ${untrusted(p.displayName)} (${Math.round(p.share * 100)}% of visitors) \u2014 ${states.join(" \xB7 ")}`);
       }
@@ -2120,7 +2179,7 @@ function registerCellTools(server, client) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
-      var _a, _b;
+      var _a, _b, _c;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/cells/detail?slotId=${encodeURIComponent(slotId)}&persona=${encodeURIComponent(persona)}`);
       const lines = [];
@@ -2132,7 +2191,12 @@ function registerCellTools(server, client) {
         lines.push("No generated version is live for this cell.");
       }
       if ((_a = data.cell) == null ? void 0 : _a.rationale) lines.push(`Why this exists: ${untrusted(data.cell.rationale, 500)}`);
-      if ((_b = data.cell) == null ? void 0 : _b.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
+      if (((_b = data.cell) == null ? void 0 : _b.refinedFrom) && (data.cell.status === "pending" || data.cell.status === "generating")) {
+        lines.push(
+          `An improved take on ${untrusted(data.cell.refinedFrom, 64)} is being written \u2014 the current version keeps serving meanwhile.`
+        );
+      }
+      if ((_c = data.cell) == null ? void 0 : _c.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
       lines.push(data.verdict);
       if (data.performance) {
         lines.push(`Shown ${data.performance.shown} times, ${data.performance.conversions} conversions.`);
@@ -2177,7 +2241,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.18.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.18.2" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {

package/dist/index.cjs

@@ -1795,8 +1795,9 @@ var import_zod13 = require("zod");
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas), learning from real conversions. Each
-project has its own persona vocabulary (dashboard -> Settings -> Personas; the default is
-buyer, researcher, deal_seeker, browser + unknown). Personas are inferred from behavior \u2014 or
+project has its own persona vocabulary (dashboard -> Settings -> Personas), and it starts
+EMPTY: every visitor is 'unknown' until a persona exists, and the optimizer learns across all
+traffic pooled in the meantime. Personas are DISCOVERED from behavior \u2014 or, far faster,
 DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
 <AdaptiveProvider persona=...> / window.sentient.persona. Declared beats inferred and serves
 at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
@@ -1809,12 +1810,14 @@ time.
 1. Run \`npx @sentientui/cli init\` (detects Next App/Pages, Vite, Remix, CRA; installs
    @sentientui/react; writes .env.local; scaffolds an example). It does NOT edit your layout \u2014
    it prints the wrap snippet for step 2.
-2. Wrap the root layout with <AdaptiveRoot apiKey context> (from '@sentientui/react/next';
-   other React apps use <AdaptiveProvider> from '@sentientui/react') and add
-   suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes pre-paint.
-   Nothing adapts and nothing is tracked until this wrap is in place.
-3. \`npm run dev\`, then open the app with \`?sentient_persona=buyer\` vs
-   \`?sentient_persona=deal_seeker\` to see it adapt. No API key needed (keyless local mode).
+2. Wrap the root layout with <AdaptiveRoot apiKey>{children}</AdaptiveRoot> (from
+   '@sentientui/react/next'; other React apps use <AdaptiveProvider> from '@sentientui/react')
+   and add suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes
+   pre-paint. Nothing adapts and nothing is tracked until this wrap is in place. Declare no
+   components here: every <Adaptive> registers itself when it renders (see Rung 2).
+3. \`npm run dev\`, then open the app with \`?sentient_persona=a\` vs
+   \`?sentient_persona=b\` to see it adapt \u2014 in keyless local mode any key drives the built-in
+   heuristic. No API key needed. Against a real project the key must be one you declared.
 4. To learn from real traffic: create a project at https://sentient-ui.com and set
    NEXT_PUBLIC_SENTIENT_API_KEY=pk_... in .env.local.
 
@@ -1823,8 +1826,8 @@ time.
 Persona attributes on <html> (zero declaration; the attribute carries the project's own
 vocabulary keys \u2014 declared or inferred):
 
-    html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
-    html[data-sentient-confidence='low'] .discount-banner { display: none; }
+    html[data-sentient-persona='admin'] .admin-tools { display: block; }
+    html[data-sentient-confidence='low'] .admin-tools { display: none; }
 
 Learned style tokens (element-scoped, SSR-safe):
 
@@ -1839,14 +1842,43 @@ prefers-reduced-motion: reduce override in CSS.
 
 ## Rung 2 \u2014 Swap (alternate content)
 
+Generated versions (start here) \u2014 wrap what the page shows today; the children are the
+original:
+
+    <Adaptive id="hero-cta" goal="signup_click">
+      <a href="/signup">Start free trial</a>
+    </Adaptive>
+
+Mount + deploy registers the region. SentientUI writes versions per visitor type in the
+dashboard ("Who sees what") \u2014 no redeploy. The children render for holdout traffic, unknown
+visitor types, types with no version yet, and every error path. Mounted regions are requested
+in one batched call after mount: the first visit shows the original briefly, then swaps; return
+visits start from the last version. Keyless local mode renders originals only.
+
+Optional server preload (Next.js App Router): registrySlotIds={['hero-cta']} for generated
+regions, components={[{ id, variantIds }]} for code variants, both on AdaptiveRoot \u2014 the first
+paint then shows the served version. List ONLY ids rendered on every page that AdaptiveRoot
+wraps (in app/layout.tsx, every route): a declared id is decided on every request, rendered or
+not, and those visits count as views that can never convert.
+
+Pass
+onFormSubmit to allow form versions; set reportBaselineText={false} on regions wrapping
+personalized or account content. (Formerly <AdaptiveSlot>.)
+
+Code variants \u2014 when you write the alternatives yourself:
+
+    <Adaptive id="buy-box" goal="buy_click"                      // goal REQUIRED
+      variants={{ control: <CalmBuyBox/>, urgent: <UrgentBuyBox/> }} />  // first key = baseline
+
+    // hook form:
     const { value, bind } = useAdaptive('buy-box', {
       variants: { calm: <CalmBuyBox/>, urgent: <UrgentBuyBox/> },  // first key = baseline
       goal: 'buy_click',                                            // REQUIRED
     });
     return <div {...bind}>{value}</div>;
 
-Always attach bind \u2014 it wires exposure tracking and goal listeners. <Adaptive> is the wrapper
-form; <AdaptiveText> swaps dashboard-managed text.
+Children or variants on one <Adaptive>, never both. With the hook, always attach bind \u2014 it
+wires exposure tracking and goal listeners. <AdaptiveText> swaps dashboard-managed text.
 
 ## Rung 3 \u2014 Reorder (structure)
 
@@ -1864,12 +1896,20 @@ their shared parent, and applies nothing if any selector drifts.
 
 ## No-code install order (snippet)
 
-Three tags in <head>, in this order: the window.sentient config, the inline pre-paint script,
-then the deferred loader. The middle tag 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 its exact bytes from the dashboard's Install page, or from
-renderSnippetPrePaintScript() in '@sentientui/snippet/install'.
+Two tags in <head>, in this order: one inline <script> that assigns the window.sentient config
+and then, in the same tag after the ';', runs the inline pre-paint script; then the deferred
+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
+the dashboard's Install page, or from renderSnippetInstall({ config }) in
+'@sentientui/snippet/install' (renderSnippetPrePaintScript() for the script alone).
+
+Strict Content-Security-Policy (script hashes): use the three-tag form instead \u2014 config, the
+pre-paint script alone, then the loader (renderSnippetInstall({ config, split: true })). The
+combined tag contains the site's config, so its hash differs per site; the split pre-paint tag is
+byte-identical everywhere, so one hash covers it. Existing three-tag and config + loader installs
+keep working.
 
 ## Testing the integration
 
@@ -2049,12 +2089,17 @@ var cellOutput = import_zod15.z.object({
   rationale: import_zod15.z.string().nullable(),
   error: import_zod15.z.string().nullable(),
   updatedAt: import_zod15.z.string(),
+  // These ride the API response too; omitting them from the schema made zod
+  // STRIP them, so agents could never see refinement or retry state.
+  refinedFrom: import_zod15.z.string().nullable().optional().describe("Incumbent arm this cell is improving on \u2014 a pending cell with this set still SERVES the incumbent"),
+  notBefore: import_zod15.z.string().nullable().optional().describe("ISO time the queue will next consider this cell (retry backoff / daily-cap deferral); null when due now"),
+  attempts: import_zod15.z.number().optional().describe("Generation attempts so far"),
   performance: import_zod15.z.object({
     shown: import_zod15.z.number(),
     conversions: import_zod15.z.number(),
     deltaPct: import_zod15.z.number().nullable().describe("Signed % vs the original conversion rate"),
     tier: import_zod15.z.string().describe("early | no_baseline | winning | losing | flat")
-  }).optional().describe("Present on live cells: the at-a-glance readout")
+  }).optional().describe("Present on live cells (and, mid-refinement, the incumbent arm): the at-a-glance readout")
 });
 function registerCellTools(server, client) {
   server.registerTool(
@@ -2064,7 +2109,15 @@ function registerCellTools(server, client) {
       description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        slots: import_zod15.z.array(import_zod15.z.object({ slotId: import_zod15.z.string(), displayName: import_zod15.z.string(), supportsForms: import_zod15.z.boolean() })),
+        slots: import_zod15.z.array(
+          import_zod15.z.object({
+            slotId: import_zod15.z.string(),
+            displayName: import_zod15.z.string(),
+            supportsForms: import_zod15.z.boolean(),
+            // API sends this; without it zod stripped the draft-vs-live signal.
+            live: import_zod15.z.boolean().optional().describe("False for an sdk-registered draft column \u2014 nothing serves until its first generation publishes it")
+          })
+        ),
         personas: import_zod15.z.array(personaOutput),
         cells: import_zod15.z.array(cellOutput),
         autoFill: import_zod15.z.boolean(),
@@ -2078,13 +2131,19 @@ function registerCellTools(server, client) {
       const data = await client.get(`/projects/${id}/cells`);
       const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
       const lines = [
-        `Slots: ${data.slots.map((s) => untrusted(s.displayName)).join(", ") || "(none published)"}`,
+        `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: ${data.personaSource}`
       ];
       for (const p of data.personas) {
         const states = data.slots.map((s) => {
           const c = byCell.get(`${s.slotId}::${p.key}`);
-          return `${untrusted(s.displayName, 40)}: ${c ? c.status : "original"}`;
+          let state = c ? c.status : "original";
+          if (c && (c.status === "pending" || c.status === "generating") && c.refinedFrom) {
+            state = `${c.status} (improving on ${untrusted(c.refinedFrom, 64)} \u2014 current version still live)`;
+          } else if (c && c.status === "pending" && c.notBefore && Date.parse(c.notBefore) > Date.now()) {
+            state = `pending (waiting until ${c.notBefore})`;
+          }
+          return `${untrusted(s.displayName, 40)}: ${state}`;
         });
         lines.push(`- ${untrusted(p.displayName)} (${Math.round(p.share * 100)}% of visitors) \u2014 ${states.join(" \xB7 ")}`);
       }
@@ -2126,7 +2185,7 @@ function registerCellTools(server, client) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
-      var _a2, _b;
+      var _a2, _b, _c;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/cells/detail?slotId=${encodeURIComponent(slotId)}&persona=${encodeURIComponent(persona)}`);
       const lines = [];
@@ -2138,7 +2197,12 @@ function registerCellTools(server, client) {
         lines.push("No generated version is live for this cell.");
       }
       if ((_a2 = data.cell) == null ? void 0 : _a2.rationale) lines.push(`Why this exists: ${untrusted(data.cell.rationale, 500)}`);
-      if ((_b = data.cell) == null ? void 0 : _b.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
+      if (((_b = data.cell) == null ? void 0 : _b.refinedFrom) && (data.cell.status === "pending" || data.cell.status === "generating")) {
+        lines.push(
+          `An improved take on ${untrusted(data.cell.refinedFrom, 64)} is being written \u2014 the current version keeps serving meanwhile.`
+        );
+      }
+      if ((_c = data.cell) == null ? void 0 : _c.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
       lines.push(data.verdict);
       if (data.performance) {
         lines.push(`Shown ${data.performance.shown} times, ${data.performance.conversions} conversions.`);
@@ -2183,7 +2247,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.18.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.18.2" : "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-PX6RCSB2.js";
+} from "./chunk-5TEQLWMW.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -1819,8 +1819,9 @@ var import_zod13 = require("zod");
 var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
 
 SentientUI adapts a site per visitor type (personas), learning from real conversions. Each
-project has its own persona vocabulary (dashboard -> Settings -> Personas; the default is
-buyer, researcher, deal_seeker, browser + unknown). Personas are inferred from behavior \u2014 or
+project has its own persona vocabulary (dashboard -> Settings -> Personas), and it starts
+EMPTY: every visitor is 'unknown' until a persona exists, and the optimizer learns across all
+traffic pooled in the meantime. Personas are DISCOVERED from behavior \u2014 or, far faster,
 DECLARED by the app when it already knows the visitor's role: init({ persona: 'admin' }) /
 <AdaptiveProvider persona=...> / window.sentient.persona. Declared beats inferred and serves
 at full confidence; unrecognized values are ignored server-side and surfaced in the dashboard
@@ -1833,12 +1834,14 @@ time.
 1. Run \`npx @sentientui/cli init\` (detects Next App/Pages, Vite, Remix, CRA; installs
    @sentientui/react; writes .env.local; scaffolds an example). It does NOT edit your layout \u2014
    it prints the wrap snippet for step 2.
-2. Wrap the root layout with <AdaptiveRoot apiKey context> (from '@sentientui/react/next';
-   other React apps use <AdaptiveProvider> from '@sentientui/react') and add
-   suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes pre-paint.
-   Nothing adapts and nothing is tracked until this wrap is in place.
-3. \`npm run dev\`, then open the app with \`?sentient_persona=buyer\` vs
-   \`?sentient_persona=deal_seeker\` to see it adapt. No API key needed (keyless local mode).
+2. Wrap the root layout with <AdaptiveRoot apiKey>{children}</AdaptiveRoot> (from
+   '@sentientui/react/next'; other React apps use <AdaptiveProvider> from '@sentientui/react')
+   and add suppressHydrationWarning to <html> \u2014 an inline script sets persona attributes
+   pre-paint. Nothing adapts and nothing is tracked until this wrap is in place. Declare no
+   components here: every <Adaptive> registers itself when it renders (see Rung 2).
+3. \`npm run dev\`, then open the app with \`?sentient_persona=a\` vs
+   \`?sentient_persona=b\` to see it adapt \u2014 in keyless local mode any key drives the built-in
+   heuristic. No API key needed. Against a real project the key must be one you declared.
 4. To learn from real traffic: create a project at https://sentient-ui.com and set
    NEXT_PUBLIC_SENTIENT_API_KEY=pk_... in .env.local.
 
@@ -1847,8 +1850,8 @@ time.
 Persona attributes on <html> (zero declaration; the attribute carries the project's own
 vocabulary keys \u2014 declared or inferred):
 
-    html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
-    html[data-sentient-confidence='low'] .discount-banner { display: none; }
+    html[data-sentient-persona='admin'] .admin-tools { display: block; }
+    html[data-sentient-confidence='low'] .admin-tools { display: none; }
 
 Learned style tokens (element-scoped, SSR-safe):
 
@@ -1863,14 +1866,43 @@ prefers-reduced-motion: reduce override in CSS.
 
 ## Rung 2 \u2014 Swap (alternate content)
 
+Generated versions (start here) \u2014 wrap what the page shows today; the children are the
+original:
+
+    <Adaptive id="hero-cta" goal="signup_click">
+      <a href="/signup">Start free trial</a>
+    </Adaptive>
+
+Mount + deploy registers the region. SentientUI writes versions per visitor type in the
+dashboard ("Who sees what") \u2014 no redeploy. The children render for holdout traffic, unknown
+visitor types, types with no version yet, and every error path. Mounted regions are requested
+in one batched call after mount: the first visit shows the original briefly, then swaps; return
+visits start from the last version. Keyless local mode renders originals only.
+
+Optional server preload (Next.js App Router): registrySlotIds={['hero-cta']} for generated
+regions, components={[{ id, variantIds }]} for code variants, both on AdaptiveRoot \u2014 the first
+paint then shows the served version. List ONLY ids rendered on every page that AdaptiveRoot
+wraps (in app/layout.tsx, every route): a declared id is decided on every request, rendered or
+not, and those visits count as views that can never convert.
+
+Pass
+onFormSubmit to allow form versions; set reportBaselineText={false} on regions wrapping
+personalized or account content. (Formerly <AdaptiveSlot>.)
+
+Code variants \u2014 when you write the alternatives yourself:
+
+    <Adaptive id="buy-box" goal="buy_click"                      // goal REQUIRED
+      variants={{ control: <CalmBuyBox/>, urgent: <UrgentBuyBox/> }} />  // first key = baseline
+
+    // hook form:
     const { value, bind } = useAdaptive('buy-box', {
       variants: { calm: <CalmBuyBox/>, urgent: <UrgentBuyBox/> },  // first key = baseline
       goal: 'buy_click',                                            // REQUIRED
     });
     return <div {...bind}>{value}</div>;
 
-Always attach bind \u2014 it wires exposure tracking and goal listeners. <Adaptive> is the wrapper
-form; <AdaptiveText> swaps dashboard-managed text.
+Children or variants on one <Adaptive>, never both. With the hook, always attach bind \u2014 it
+wires exposure tracking and goal listeners. <AdaptiveText> swaps dashboard-managed text.
 
 ## Rung 3 \u2014 Reorder (structure)
 
@@ -1888,12 +1920,20 @@ their shared parent, and applies nothing if any selector drifts.
 
 ## No-code install order (snippet)
 
-Three tags in <head>, in this order: the window.sentient config, the inline pre-paint script,
-then the deferred loader. The middle tag 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 its exact bytes from the dashboard's Install page, or from
-renderSnippetPrePaintScript() in '@sentientui/snippet/install'.
+Two tags in <head>, in this order: one inline <script> that assigns the window.sentient config
+and then, in the same tag after the ';', runs the inline pre-paint script; then the deferred
+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
+the dashboard's Install page, or from renderSnippetInstall({ config }) in
+'@sentientui/snippet/install' (renderSnippetPrePaintScript() for the script alone).
+
+Strict Content-Security-Policy (script hashes): use the three-tag form instead \u2014 config, the
+pre-paint script alone, then the loader (renderSnippetInstall({ config, split: true })). The
+combined tag contains the site's config, so its hash differs per site; the split pre-paint tag is
+byte-identical everywhere, so one hash covers it. Existing three-tag and config + loader installs
+keep working.
 
 ## Testing the integration
 
@@ -2073,12 +2113,17 @@ var cellOutput = import_zod15.z.object({
   rationale: import_zod15.z.string().nullable(),
   error: import_zod15.z.string().nullable(),
   updatedAt: import_zod15.z.string(),
+  // These ride the API response too; omitting them from the schema made zod
+  // STRIP them, so agents could never see refinement or retry state.
+  refinedFrom: import_zod15.z.string().nullable().optional().describe("Incumbent arm this cell is improving on \u2014 a pending cell with this set still SERVES the incumbent"),
+  notBefore: import_zod15.z.string().nullable().optional().describe("ISO time the queue will next consider this cell (retry backoff / daily-cap deferral); null when due now"),
+  attempts: import_zod15.z.number().optional().describe("Generation attempts so far"),
   performance: import_zod15.z.object({
     shown: import_zod15.z.number(),
     conversions: import_zod15.z.number(),
     deltaPct: import_zod15.z.number().nullable().describe("Signed % vs the original conversion rate"),
     tier: import_zod15.z.string().describe("early | no_baseline | winning | losing | flat")
-  }).optional().describe("Present on live cells: the at-a-glance readout")
+  }).optional().describe("Present on live cells (and, mid-refinement, the incumbent arm): the at-a-glance readout")
 });
 function registerCellTools(server, client) {
   server.registerTool(
@@ -2088,7 +2133,15 @@ function registerCellTools(server, client) {
       description: 'The "Who sees what" matrix: which visitor types (personas) have an AI-generated version live in each personalizable region (slot), with per-persona traffic share and the first-miss auto-fill setting. A cell with no row means that visitor type sees the original.' + UNTRUSTED_FIELDS_NOTE,
       inputSchema: { projectId: projectIdSchema },
       outputSchema: {
-        slots: import_zod15.z.array(import_zod15.z.object({ slotId: import_zod15.z.string(), displayName: import_zod15.z.string(), supportsForms: import_zod15.z.boolean() })),
+        slots: import_zod15.z.array(
+          import_zod15.z.object({
+            slotId: import_zod15.z.string(),
+            displayName: import_zod15.z.string(),
+            supportsForms: import_zod15.z.boolean(),
+            // API sends this; without it zod stripped the draft-vs-live signal.
+            live: import_zod15.z.boolean().optional().describe("False for an sdk-registered draft column \u2014 nothing serves until its first generation publishes it")
+          })
+        ),
         personas: import_zod15.z.array(personaOutput),
         cells: import_zod15.z.array(cellOutput),
         autoFill: import_zod15.z.boolean(),
@@ -2102,13 +2155,19 @@ function registerCellTools(server, client) {
       const data = await client.get(`/projects/${id}/cells`);
       const byCell = new Map(data.cells.map((c) => [`${c.slotId}::${c.persona}`, c]));
       const lines = [
-        `Slots: ${data.slots.map((s) => untrusted(s.displayName)).join(", ") || "(none published)"}`,
+        `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: ${data.personaSource}`
       ];
       for (const p of data.personas) {
         const states = data.slots.map((s) => {
           const c = byCell.get(`${s.slotId}::${p.key}`);
-          return `${untrusted(s.displayName, 40)}: ${c ? c.status : "original"}`;
+          let state = c ? c.status : "original";
+          if (c && (c.status === "pending" || c.status === "generating") && c.refinedFrom) {
+            state = `${c.status} (improving on ${untrusted(c.refinedFrom, 64)} \u2014 current version still live)`;
+          } else if (c && c.status === "pending" && c.notBefore && Date.parse(c.notBefore) > Date.now()) {
+            state = `pending (waiting until ${c.notBefore})`;
+          }
+          return `${untrusted(s.displayName, 40)}: ${state}`;
         });
         lines.push(`- ${untrusted(p.displayName)} (${Math.round(p.share * 100)}% of visitors) \u2014 ${states.join(" \xB7 ")}`);
       }
@@ -2150,7 +2209,7 @@ function registerCellTools(server, client) {
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
     },
     withApiErrorGuidance(async ({ projectId, slotId, persona }) => {
-      var _a, _b;
+      var _a, _b, _c;
       const id = encodeURIComponent(projectId);
       const data = await client.get(`/projects/${id}/cells/detail?slotId=${encodeURIComponent(slotId)}&persona=${encodeURIComponent(persona)}`);
       const lines = [];
@@ -2162,7 +2221,12 @@ function registerCellTools(server, client) {
         lines.push("No generated version is live for this cell.");
       }
       if ((_a = data.cell) == null ? void 0 : _a.rationale) lines.push(`Why this exists: ${untrusted(data.cell.rationale, 500)}`);
-      if ((_b = data.cell) == null ? void 0 : _b.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
+      if (((_b = data.cell) == null ? void 0 : _b.refinedFrom) && (data.cell.status === "pending" || data.cell.status === "generating")) {
+        lines.push(
+          `An improved take on ${untrusted(data.cell.refinedFrom, 64)} is being written \u2014 the current version keeps serving meanwhile.`
+        );
+      }
+      if ((_c = data.cell) == null ? void 0 : _c.error) lines.push(`Last attempt failed: ${untrusted(data.cell.error, 300)}`);
       lines.push(data.verdict);
       if (data.performance) {
         lines.push(`Shown ${data.performance.shown} times, ${data.performance.conversions} conversions.`);
@@ -2207,7 +2271,7 @@ function registerCellTools(server, client) {
 }
 
 // src/server.ts
-var PKG_VERSION = true ? "0.18.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.18.2" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {

package/dist/lib.js

@@ -4,7 +4,7 @@ import {
   ApiError,
   PUBLIC_UI_RESOURCE_URIS,
   createMcpServer
-} from "./chunk-PX6RCSB2.js";
+} from "./chunk-5TEQLWMW.js";
 export {
   ApiClient,
   ApiError,

package/package.json

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