@sentientui/mcp 0.2.2 → 0.3.1

package/AGENTS.md

@@ -6,7 +6,12 @@ SentientUI is a UI personalization platform that assigns visitors to variant com
 
 **Persona / Cluster** — visitors are clustered by behavior into labeled groups. A `reliability_score` (0–1) measures confidence in the assignment. Low reliability means the engine won't personalize for that session even if a cluster is assigned.
 
-**Variant** — a version of an adaptive component. Variants start as **draft** after `create_variant`; they must be activated from the dashboard before traffic is assigned. There is no MCP tool to activate or resume variants.
+**Variant** — a version of an adaptive component. There are **two kinds**, and the difference matters:
+
+- **Code-native variants** are declared in the customer's code (`<Adaptive variants={{…}}>`). They **register automatically** the first time the SDK requests an assignment after deploy, and they go **live immediately** — there is no draft step and no `create_variant` call. Their content lives in the repo, not in SentientUI.
+- **No-code / managed variants** have no code; their content is stored on the SentientUI API (dashboard WYSIWYG, `<AdaptiveText>`, or `create_variant`). These start as **draft** after `create_variant` and must be activated from the dashboard before traffic is assigned. There is no MCP tool to activate or resume variants.
+
+Only call `create_variant` for the no-code path. If the user is writing (or you are writing) the variant in code, do **not** call `create_variant` — deploying the code registers it.
 
 **Guardrail** — automatic safety circuit that pauses variants whose CVR drops below threshold. `list_guardrail_events` shows what's been paused. Pausing via `pause_variant` is irreversible via MCP (no resume tool).
 
@@ -34,7 +39,8 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 | `get_layout_stats` | Per-persona layout order + bandit pulls/reward |
 | `get_insights` | Narrator bullets + (Growth) advisor bullets |
 | `refresh_insights` | Async trigger — wait ~15s then call `get_insights` |
-| `create_variant` | Creates DRAFT — user must activate in dashboard |
+| `get_variant_brief` | **Start here to optimize a component.** Insight-driven brief for writing a new CODE-NATIVE variant: performance, audience, insights, data-sufficiency + best-practice fallback, and code instructions |
+| `create_variant` | Creates a no-code **managed text** DRAFT — user must activate in dashboard. Fallback only; not for code-native variants |
 | `pause_variant` | Stops traffic; no MCP resume |
 
 ## Canonical Workflows
@@ -46,9 +52,18 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 4. `list_guardrail_events` — see if the guardrail fired
 5. `refresh_insights` → wait 15s → `get_insights` — read AI summary
 
-**Add a new variant**
+**Optimize a component with a new variant (code-native — recommended)**
+1. `list_components` — confirm the component ID
+2. `get_variant_brief` — pull performance, audience, insights, data-sufficiency, best-practice priors, and code instructions for that component
+3. Find `<Adaptive id="...">` in the repo and add a new on-brand variant key to its `variants` map (and to the `AdaptiveRoot` `components` list if SSR). Match the project's existing components and design system.
+4. Do **not** call `create_variant`. Commit, push, deploy — the variant auto-registers on the first assignment and goes live.
+5. Optional: enable shadow mode for the component first to validate before serving.
+
+Data sufficiency (from the brief) drives the change: when it reports **SUFFICIENT**, target the specific weakness; when **COLLECTING** or **EMPTY** (no data yet), apply the best-practice priors for the project's context type — use your best judgment and make one conservative change.
+
+**Add a no-code managed text variant (fallback — text only, less powerful)**
 1. `list_components` — confirm the component ID
-2. `create_variant` — creates draft
+2. `create_variant` with `content` — creates a managed text draft (generate the copy from `get_variant_brief` context)
 3. Tell the user to activate it from the dashboard
 
 **Understand the audience**
@@ -65,6 +80,8 @@ Server keys start with `sk_` — required for the management API. Public keys (`
 
 - Presenting stale insights without checking `isStale` — always check, and offer to `refresh_insights`
 - Assuming `create_variant` is live — it's always a draft
+- Calling `create_variant` for a variant that's being written in code — it creates an empty managed draft, not your code variant. Code-native variants auto-register on deploy; only use `create_variant` for no-code/managed variants whose content lives in SentientUI
+- Optimizing a component without calling `get_variant_brief` first — it gives you the performance, audience, insights, and data-sufficiency fallback you need to write a variant that actually makes sense (and the right steps when there is no data yet)
 - Calling `pause_variant` without warning the user it's irreversible via MCP
 - Using a `pk_` key instead of `sk_` — it will be rejected
 - Interpreting `avgReward` in layout stats as a conversion rate — it's a bandit reward signal, not CVR

package/README.md

@@ -82,9 +82,14 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-
 | `get_goal_funnel` | Goal hit counts and conversion rates per variant |
 | `list_guardrail_events` | Variants auto-paused by the guardrail (last 24h) |
 | `get_layout_stats` | Per-persona section layout rankings and reward weights |
-| `create_variant` | Create a new draft variant (Starter+) |
+| `get_variant_brief` | Insight-driven brief for writing a new **code-native** variant: performance, audience, insights, data-sufficiency (with a best-practice fallback when there's no data yet), and step-by-step code instructions |
+| `create_variant` | Create a no-code (managed) text variant (Starter+) — fallback for text-only variants without a code change |
 | `pause_variant` | Pause a variant to stop traffic assignment |
 
+> **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.
+
 ## Example prompts
 
 - *"What projects do I have?"*
@@ -92,6 +97,7 @@ A sandboxed demo token is provisioned automatically — 10 calls/month, no sign-
 - *"Are any variants paused by the guardrail right now?"*
 - *"What do the AI insights say about what changed this week?"*
 - *"Refresh insights for project X"*
+- *"Optimize my hero CTA — pull the brief and add a new variant in the code"*
 - *"Create a new variant called 'short-copy' for the pricing CTA"*
 
 ## Configuration

package/dist/index.cjs

@@ -175,9 +175,10 @@ function registerPersonaTools(server, client) {
         `Total sessions: ${data.totalSessions}`,
         "",
         "Clusters:",
-        ...data.clusters.map(
-          (c) => `- ${c.label}: ${c.sessionCount} sessions (${(c.sessionCount / data.totalSessions * 100).toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`
-        )
+        ...data.clusters.map((c) => {
+          const pct = data.totalSessions > 0 ? c.sessionCount / data.totalSessions * 100 : 0;
+          return `- ${c.label}: ${c.sessionCount} sessions (${pct.toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`;
+        })
       ];
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -258,22 +259,24 @@ var projectIdSchema8 = import_zod8.z.string().uuid().describe("The project UUID"
 function registerVariantWriteTools(server, client) {
   server.tool(
     "create_variant",
-    "Create a new draft variant for a component. Requires Starter or Growth plan.",
+    "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 Starter or Growth plan.",
     {
       projectId: projectIdSchema8,
       componentId: import_zod8.z.string().describe("The component ID to add a variant to"),
-      displayName: import_zod8.z.string().describe("Human-readable name for the new variant")
+      displayName: import_zod8.z.string().describe("Human-readable name for the new variant"),
+      content: import_zod8.z.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
     },
-    async ({ projectId, componentId, displayName }) => {
+    async ({ projectId, componentId, displayName, content }) => {
       const id = encodeURIComponent(projectId);
       const result = await client.post(
         `/projects/${id}/variants`,
-        { componentId, displayName }
+        { componentId, displayName, content }
       );
+      const contentNote = content ? " with the provided text content" : " (empty \u2014 add its text content from the dashboard or via a follow-up update)";
       return {
         content: [{
           type: "text",
-          text: `Variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}. It is in draft state \u2014 activate it from the dashboard.`
+          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).`
         }]
       };
     }
@@ -314,6 +317,334 @@ function registerVariantWriteTools(server, client) {
   );
 }
 
+// src/tools/variant-brief.ts
+var import_zod9 = require("zod");
+var projectIdSchema9 = import_zod9.z.string().uuid().describe("The project UUID");
+var GOAL_TARGET = 500;
+var BEST_PRACTICE_PRIORS = {
+  ecommerce: [
+    "Lead with the core benefit/value, not features.",
+    "Make the primary action (add to cart / buy) unmistakable and high-contrast.",
+    "Reduce purchase anxiety near the decision: free returns, shipping, secure checkout, guarantees.",
+    'Add credible social proof (ratings, review count, "X sold").',
+    "Use urgency/scarcity only when it is genuinely true (low stock, real deadline).",
+    "Cut friction: fewer steps, clearer pricing, no surprise costs."
+  ],
+  saas: [
+    "Lead with the outcome the user gets, not the mechanism.",
+    'Make the primary CTA action-oriented and specific (e.g. "Start free trial").',
+    'Reduce signup friction (fewer fields, SSO, "no credit card required").',
+    "Add proof near the CTA: customer logos, a hard metric, a short testimonial.",
+    "Address the target persona's top objection inline."
+  ],
+  landing: [
+    "One clear message and one primary action above the fold.",
+    "Match the headline to the traffic source / campaign intent.",
+    "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."
+  ]
+};
+var GENERIC_PRIORS = [
+  "Make the primary action unmistakable and benefit-led.",
+  "Lead with the outcome/value for the visitor.",
+  "Remove friction and distractions around the decision.",
+  "Add one credible proof point near the action."
+];
+function priorsFor(contextType) {
+  return BEST_PRACTICE_PRIORS[contextType] ?? GENERIC_PRIORS;
+}
+function computeDataState(impressions, insights, avgReliability) {
+  if (impressions === 0) return "empty";
+  const insightsReady = insights?.status === "ok" && !insights.isStale;
+  const reliable = avgReliability === null || avgReliability >= 0.3;
+  if (impressions < GOAL_TARGET || !insightsReady || !reliable) return "collecting";
+  return "sufficient";
+}
+function guidanceFor(dataState, contextType) {
+  switch (dataState) {
+    case "sufficient":
+      return "There is enough data. Target the specific weakness above \u2014 the underperforming variant/persona \u2014 with your change. Set basis to the signal you used.";
+    case "collecting":
+      return "Limited data so far. Lean on the best-practice priors below, lightly informed by the early signal. Make one focused change rather than a redesign.";
+    case "empty":
+      return `No data yet \u2014 use your best judgment. Apply the best-practice priors for a ${contextType} surface below. Make one conservative, high-confidence change, and consider enabling shadow mode for this component so it is validated before it serves real traffic.`;
+  }
+}
+async function settled(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerVariantBriefTools(server, client) {
+  server.tool(
+    "get_variant_brief",
+    "Get an insight-driven brief for creating a new CODE-NATIVE variant of a component. Returns current variant performance, audience, insights, a data-sufficiency assessment (with a best-practice fallback when there is no data yet), and step-by-step instructions for writing the variant in the customer's code. Use this instead of create_variant when the variant will live in the codebase.",
+    {
+      projectId: projectIdSchema9,
+      componentId: import_zod9.z.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [projects, components, trends, portraits, insights] = await Promise.all([
+        settled(client.get("/projects")),
+        settled(client.get(`/projects/${id}/components`)),
+        settled(client.get(`/projects/${id}/trends`)),
+        settled(client.get(`/projects/${id}/portraits`)),
+        settled(client.get(`/projects/${id}/insights`))
+      ]);
+      const project = projects?.find((p) => p.id === projectId) ?? null;
+      const contextType = project?.context_type ?? "unknown";
+      const component = components?.find((c) => c.component_id === componentId) ?? null;
+      const impressions = component?.total_impressions ?? 0;
+      const conversions = component?.total_conversions ?? 0;
+      const componentCvr = impressions > 0 ? conversions / impressions * 100 : 0;
+      const existingVariantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      const variantIdSet = new Set(existingVariantIds);
+      const momentumMap = new Map((trends?.momentum ?? []).map((m) => [m.variantId, m.direction]));
+      const variantPerf = (trends?.cvr ?? []).filter((v) => variantIdSet.has(v.variantId));
+      const clusters = portraits?.clusters ?? [];
+      const totalSessions = portraits?.totalSessions ?? 0;
+      const avgReliability = clusters.length ? clusters.reduce((s, c) => s + c.avgReliability, 0) / clusters.length : null;
+      const dataState = computeDataState(impressions, insights, avgReliability);
+      const lines = [];
+      lines.push(`# Variant brief \u2014 ${componentId}`);
+      lines.push(`Project context type: ${contextType}`);
+      lines.push("");
+      if (!component) {
+        lines.push(
+          `Note: no component named "${componentId}" has reported data yet. If this is a new <Adaptive> you are adding, that is expected \u2014 it registers automatically on first assignment after deploy. Proceed using the best-practice priors below.`
+        );
+        lines.push("");
+      } else {
+        lines.push(
+          `Component performance: ${impressions} impressions, ${conversions} conversions, ${componentCvr.toFixed(2)}% CVR.`
+        );
+        lines.push(
+          `Existing variant IDs (do not reuse these): ${existingVariantIds.length ? existingVariantIds.join(", ") : "(none)"}`
+        );
+        lines.push("");
+      }
+      if (variantPerf.length) {
+        lines.push("Current variant performance (7d vs prior 7d):");
+        for (const v of variantPerf) {
+          lines.push(
+            `- ${v.variantId}: ${(v.currentCvr * 100).toFixed(2)}% CVR (${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${momentumMap.get(v.variantId) ?? "stable"})`
+          );
+        }
+        lines.push("");
+      }
+      if (clusters.length) {
+        lines.push(`Audience (${totalSessions} sessions):`);
+        for (const c of clusters) {
+          const share = totalSessions > 0 ? (c.sessionCount / totalSessions * 100).toFixed(0) : "0";
+          lines.push(`- ${c.label}: ${share}% of traffic (reliability ${(c.avgReliability * 100).toFixed(0)}%)`);
+        }
+        lines.push("");
+      }
+      if (insights && insights.status === "ok") {
+        if (insights.isStale) lines.push("\u26A0 Insights are stale (>6h). Consider refresh_insights for a fresher read.");
+        const narrator = insights.narratorBullets ?? [];
+        const advisor = insights.advisorBullets ?? [];
+        if (narrator.length) {
+          lines.push("Insights \u2014 observations:");
+          narrator.forEach((b) => lines.push(`- ${b}`));
+        }
+        if (advisor.length) {
+          lines.push("Insights \u2014 recommendations:");
+          advisor.forEach((b) => lines.push(`- ${b}`));
+        }
+        lines.push("");
+      } else {
+        lines.push("Insights: none generated yet.");
+        lines.push("");
+      }
+      lines.push(`## Data sufficiency: ${dataState.toUpperCase()}`);
+      lines.push(guidanceFor(dataState, contextType));
+      lines.push("");
+      lines.push(`## Best-practice priors (${contextType})`);
+      priorsFor(contextType).forEach((p) => lines.push(`- ${p}`));
+      lines.push("");
+      lines.push("## How to implement (code-native variant)");
+      lines.push(`1. Search the repository for <Adaptive id="${componentId}"> (and any matching useAssignment("${componentId}") usage).`);
+      lines.push('2. Add a new key to its `variants` map with on-brand JSX that matches the surrounding components and the project\'s design system. Pick a short, descriptive new variant id that is not in the existing list above (e.g. "value_led", "social_proof", "urgency").');
+      lines.push("3. If the component is server-rendered via <AdaptiveRoot>, add the new variant id to that component's entry in the `components` list so it is included in SSR preloading.");
+      lines.push("4. Do NOT call create_variant \u2014 that creates a separate no-code MANAGED draft. Code-native variants register automatically on the first assignment after you deploy, and go live immediately.");
+      lines.push("5. Commit, push, and deploy. Optionally enable shadow mode for this component first if you want to validate before serving real traffic.");
+      lines.push("");
+      lines.push("Make the change reflect the data sufficiency above: data-driven when SUFFICIENT, best-practice-led when COLLECTING or EMPTY.");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/test-brief.ts
+var import_zod10 = require("zod");
+var projectIdSchema10 = import_zod10.z.string().uuid().describe("The project UUID");
+async function settled2(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerTestBriefTools(server, client) {
+  server.tool(
+    "get_test_brief",
+    "Get a ready-to-paste test for a SentientUI-wrapped component, populated with the component's real variants and goals. This project uses @sentientui/react/testing. Use this so your tests force a specific variant/layout deterministically and never break when the optimizer serves a different version. Returns a React Testing Library example plus the URL-param recipe for E2E (Playwright/Cypress).",
+    {
+      projectId: projectIdSchema10,
+      componentId: import_zod10.z.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [components, goalsRes] = await Promise.all([
+        settled2(client.get(`/projects/${id}/components`)),
+        settled2(client.get(`/projects/${id}/goals`))
+      ]);
+      const component = components?.find((c) => c.component_id === componentId) ?? null;
+      const variantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      const goals = Array.isArray(goalsRes) ? goalsRes : goalsRes?.goals ?? [];
+      const goalName = goals[0]?.goalName ?? "signup";
+      const controlId = variantIds[0] ?? "control";
+      const forcedId = variantIds.find((v) => v !== controlId) ?? "variant_b";
+      const lines = [];
+      lines.push(`# Test brief \u2014 ${componentId}`);
+      lines.push("");
+      lines.push("This project uses **`@sentientui/react/testing`**. By default SentientUI serves the *control* variant and default layout in tests and sends no events, so existing tests are unaffected. Pass a scenario to force a specific variant/layout.");
+      if (!component) {
+        lines.push("");
+        lines.push(`Note: no component named "${componentId}" has reported data yet. If you are adding this \`<Adaptive>\`, that is expected \u2014 the example below uses placeholder variant IDs; replace them with the ones you declare in \`variants={{ \u2026 }}\`.`);
+      }
+      lines.push("");
+      lines.push("## React Testing Library");
+      lines.push("```tsx");
+      lines.push(`import { renderWithSentient } from '@sentientui/react/testing';`);
+      lines.push(`import { screen } from '@testing-library/react';`);
+      lines.push("");
+      lines.push(`test('${componentId}: forces the "${forcedId}" variant', () => {`);
+      lines.push(`  renderWithSentient(<YourPage />, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // assert on the ${forcedId} variant's content:`);
+      lines.push(`  // expect(screen.getByText('\u2026')).toBeInTheDocument();`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## Assert a goal fires (with the mock server)");
+      lines.push("```tsx");
+      lines.push(`import { setupSentientServer } from '@sentientui/react/testing/node';`);
+      lines.push(`import { getSentientEvents, hasFiredGoal } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = setupSentientServer();`);
+      lines.push(`afterAll(() => s.server.close());`);
+      lines.push("");
+      lines.push(`test('${componentId}: fires the ${goalName} goal', async () => {`);
+      lines.push(`  s.use({ variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // \u2026render with a live client, trigger the interaction\u2026`);
+      lines.push(`  expect(hasFiredGoal(getSentientEvents(), '${goalName}')).toBe(true);`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## E2E (Playwright / Cypress)");
+      lines.push(`Use \`mockSentient\` to force variants/layout, stub the API, and capture events:`);
+      lines.push("```ts");
+      lines.push(`import { mockSentient } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = await mockSentient(page, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`await page.goto('/');`);
+      lines.push(`expect(s.events().some((e) => e.goalType === '${goalName}')).toBe(true);`);
+      lines.push("```");
+      lines.push(`Cypress: \`mockSentientCypress(cy, scenario)\` in a beforeEach. **Prefer mockSentient in CI \u2014 it writes nothing.**`);
+      lines.push(`The URL param below is fine for a quick local pin, but a live client still creates an (automation-flagged) session:`);
+      lines.push("```ts");
+      lines.push(`await page.goto('/?sentient_variant=${componentId}:${forcedId}');`);
+      lines.push("```");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/integration-guide.ts
+var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
+
+SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
+unknown), learning from real conversions. Decisions are locked per session: Visit 1 learns,
+Visit 2 converts. Integrate one rung at a time.
+
+## Setup (60 seconds, no account)
+
+1. Run \`npx @sentientui/cli init\` (detects Next App/Pages, Vite, Remix, CRA; installs
+   @sentientui/react; wraps the app; writes .env.local; scaffolds an example).
+2. \`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).
+3. To learn from real traffic: create a project at https://sentient-ui.com and set
+   NEXT_PUBLIC_SENTIENT_API_KEY=pk_... in .env.local.
+
+Manual setup: 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.
+
+## Rung 1 \u2014 Style (CSS only)
+
+Persona attributes on <html> (zero declaration):
+
+    html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
+    html[data-sentient-confidence='low'] .discount-banner { display: none; }
+
+Learned style tokens (element-scoped, SSR-safe):
+
+    const t = useAdaptiveTokens('hero', {
+      tone: ['calm', 'urgent'],   // first value = baseline
+    });
+    return <section {...t.props} className="hero">\u2026</section>;
+    // CSS: .hero[data-tone='urgent'] .cta { font-weight: 700; }
+
+Rules: 1-4 dims, 2-6 values each, enum values only. For animation values, always add a
+prefers-reduced-motion: reduce override in CSS.
+
+## Rung 2 \u2014 Swap (alternate content)
+
+    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.
+
+## Rung 3 \u2014 Reorder (structure)
+
+    <AdaptiveGroup id="pricing-area" arrangements={{
+      standard:     ['plans', 'faq', 'social'],   // first key = baseline
+      social_first: ['social', 'plans', 'faq'],
+    }}>
+      <PlanGrid key="plans"/> <Faq key="faq"/> <Testimonials key="social"/>
+    </AdaptiveGroup>
+
+Declared orders of keyed children only. Page-level: sections={[...]} on AdaptiveRoot +
+useLayoutOrder().
+
+## Testing the integration
+
+Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, persona }) forces
+deterministic outcomes so tests never depend on what the optimizer serves.
+`;
+function registerIntegrationGuideTools(server) {
+  server.tool(
+    "get_integration_guide",
+    "Get the SentientUI adaptive-ladder integration guide: setup (keyless and keyed) plus copy-pasteable examples for every rung (Style, Swap, Reorder). Use this to integrate SentientUI into a codebase.",
+    {},
+    async () => ({ content: [{ type: "text", text: GUIDE }] })
+  );
+}
+
 // src/server.ts
 function createMcpServer(client) {
   const server = new import_mcp.McpServer({
@@ -327,7 +658,10 @@ function createMcpServer(client) {
   registerGoalTools(server, client);
   registerGuardrailTools(server, client);
   registerLayoutTools(server, client);
+  registerVariantBriefTools(server, client);
+  registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
+  registerIntegrationGuideTools(server);
   return server;
 }
 

package/dist/index.js

@@ -174,9 +174,10 @@ function registerPersonaTools(server, client) {
         `Total sessions: ${data.totalSessions}`,
         "",
         "Clusters:",
-        ...data.clusters.map(
-          (c) => `- ${c.label}: ${c.sessionCount} sessions (${(c.sessionCount / data.totalSessions * 100).toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`
-        )
+        ...data.clusters.map((c) => {
+          const pct = data.totalSessions > 0 ? c.sessionCount / data.totalSessions * 100 : 0;
+          return `- ${c.label}: ${c.sessionCount} sessions (${pct.toFixed(1)}% of traffic, reliability ${(c.avgReliability * 100).toFixed(0)}%)`;
+        })
       ];
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -257,22 +258,24 @@ var projectIdSchema8 = z8.string().uuid().describe("The project UUID");
 function registerVariantWriteTools(server, client) {
   server.tool(
     "create_variant",
-    "Create a new draft variant for a component. Requires Starter or Growth plan.",
+    "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 Starter or Growth plan.",
     {
       projectId: projectIdSchema8,
       componentId: z8.string().describe("The component ID to add a variant to"),
-      displayName: z8.string().describe("Human-readable name for the new variant")
+      displayName: z8.string().describe("Human-readable name for the new variant"),
+      content: z8.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
     },
-    async ({ projectId, componentId, displayName }) => {
+    async ({ projectId, componentId, displayName, content }) => {
       const id = encodeURIComponent(projectId);
       const result = await client.post(
         `/projects/${id}/variants`,
-        { componentId, displayName }
+        { componentId, displayName, content }
       );
+      const contentNote = content ? " with the provided text content" : " (empty \u2014 add its text content from the dashboard or via a follow-up update)";
       return {
         content: [{
           type: "text",
-          text: `Variant created: ${result.variantId} ("${result.displayName}") for component ${componentId}. It is in draft state \u2014 activate it from the dashboard.`
+          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).`
         }]
       };
     }
@@ -313,6 +316,334 @@ function registerVariantWriteTools(server, client) {
   );
 }
 
+// src/tools/variant-brief.ts
+import { z as z9 } from "zod";
+var projectIdSchema9 = z9.string().uuid().describe("The project UUID");
+var GOAL_TARGET = 500;
+var BEST_PRACTICE_PRIORS = {
+  ecommerce: [
+    "Lead with the core benefit/value, not features.",
+    "Make the primary action (add to cart / buy) unmistakable and high-contrast.",
+    "Reduce purchase anxiety near the decision: free returns, shipping, secure checkout, guarantees.",
+    'Add credible social proof (ratings, review count, "X sold").',
+    "Use urgency/scarcity only when it is genuinely true (low stock, real deadline).",
+    "Cut friction: fewer steps, clearer pricing, no surprise costs."
+  ],
+  saas: [
+    "Lead with the outcome the user gets, not the mechanism.",
+    'Make the primary CTA action-oriented and specific (e.g. "Start free trial").',
+    'Reduce signup friction (fewer fields, SSO, "no credit card required").',
+    "Add proof near the CTA: customer logos, a hard metric, a short testimonial.",
+    "Address the target persona's top objection inline."
+  ],
+  landing: [
+    "One clear message and one primary action above the fold.",
+    "Match the headline to the traffic source / campaign intent.",
+    "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."
+  ]
+};
+var GENERIC_PRIORS = [
+  "Make the primary action unmistakable and benefit-led.",
+  "Lead with the outcome/value for the visitor.",
+  "Remove friction and distractions around the decision.",
+  "Add one credible proof point near the action."
+];
+function priorsFor(contextType) {
+  return BEST_PRACTICE_PRIORS[contextType] ?? GENERIC_PRIORS;
+}
+function computeDataState(impressions, insights, avgReliability) {
+  if (impressions === 0) return "empty";
+  const insightsReady = insights?.status === "ok" && !insights.isStale;
+  const reliable = avgReliability === null || avgReliability >= 0.3;
+  if (impressions < GOAL_TARGET || !insightsReady || !reliable) return "collecting";
+  return "sufficient";
+}
+function guidanceFor(dataState, contextType) {
+  switch (dataState) {
+    case "sufficient":
+      return "There is enough data. Target the specific weakness above \u2014 the underperforming variant/persona \u2014 with your change. Set basis to the signal you used.";
+    case "collecting":
+      return "Limited data so far. Lean on the best-practice priors below, lightly informed by the early signal. Make one focused change rather than a redesign.";
+    case "empty":
+      return `No data yet \u2014 use your best judgment. Apply the best-practice priors for a ${contextType} surface below. Make one conservative, high-confidence change, and consider enabling shadow mode for this component so it is validated before it serves real traffic.`;
+  }
+}
+async function settled(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerVariantBriefTools(server, client) {
+  server.tool(
+    "get_variant_brief",
+    "Get an insight-driven brief for creating a new CODE-NATIVE variant of a component. Returns current variant performance, audience, insights, a data-sufficiency assessment (with a best-practice fallback when there is no data yet), and step-by-step instructions for writing the variant in the customer's code. Use this instead of create_variant when the variant will live in the codebase.",
+    {
+      projectId: projectIdSchema9,
+      componentId: z9.string().describe('The component ID to write a new variant for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [projects, components, trends, portraits, insights] = await Promise.all([
+        settled(client.get("/projects")),
+        settled(client.get(`/projects/${id}/components`)),
+        settled(client.get(`/projects/${id}/trends`)),
+        settled(client.get(`/projects/${id}/portraits`)),
+        settled(client.get(`/projects/${id}/insights`))
+      ]);
+      const project = projects?.find((p) => p.id === projectId) ?? null;
+      const contextType = project?.context_type ?? "unknown";
+      const component = components?.find((c) => c.component_id === componentId) ?? null;
+      const impressions = component?.total_impressions ?? 0;
+      const conversions = component?.total_conversions ?? 0;
+      const componentCvr = impressions > 0 ? conversions / impressions * 100 : 0;
+      const existingVariantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      const variantIdSet = new Set(existingVariantIds);
+      const momentumMap = new Map((trends?.momentum ?? []).map((m) => [m.variantId, m.direction]));
+      const variantPerf = (trends?.cvr ?? []).filter((v) => variantIdSet.has(v.variantId));
+      const clusters = portraits?.clusters ?? [];
+      const totalSessions = portraits?.totalSessions ?? 0;
+      const avgReliability = clusters.length ? clusters.reduce((s, c) => s + c.avgReliability, 0) / clusters.length : null;
+      const dataState = computeDataState(impressions, insights, avgReliability);
+      const lines = [];
+      lines.push(`# Variant brief \u2014 ${componentId}`);
+      lines.push(`Project context type: ${contextType}`);
+      lines.push("");
+      if (!component) {
+        lines.push(
+          `Note: no component named "${componentId}" has reported data yet. If this is a new <Adaptive> you are adding, that is expected \u2014 it registers automatically on first assignment after deploy. Proceed using the best-practice priors below.`
+        );
+        lines.push("");
+      } else {
+        lines.push(
+          `Component performance: ${impressions} impressions, ${conversions} conversions, ${componentCvr.toFixed(2)}% CVR.`
+        );
+        lines.push(
+          `Existing variant IDs (do not reuse these): ${existingVariantIds.length ? existingVariantIds.join(", ") : "(none)"}`
+        );
+        lines.push("");
+      }
+      if (variantPerf.length) {
+        lines.push("Current variant performance (7d vs prior 7d):");
+        for (const v of variantPerf) {
+          lines.push(
+            `- ${v.variantId}: ${(v.currentCvr * 100).toFixed(2)}% CVR (${v.deltaPp > 0 ? "+" : ""}${v.deltaPp.toFixed(1)} pp, ${momentumMap.get(v.variantId) ?? "stable"})`
+          );
+        }
+        lines.push("");
+      }
+      if (clusters.length) {
+        lines.push(`Audience (${totalSessions} sessions):`);
+        for (const c of clusters) {
+          const share = totalSessions > 0 ? (c.sessionCount / totalSessions * 100).toFixed(0) : "0";
+          lines.push(`- ${c.label}: ${share}% of traffic (reliability ${(c.avgReliability * 100).toFixed(0)}%)`);
+        }
+        lines.push("");
+      }
+      if (insights && insights.status === "ok") {
+        if (insights.isStale) lines.push("\u26A0 Insights are stale (>6h). Consider refresh_insights for a fresher read.");
+        const narrator = insights.narratorBullets ?? [];
+        const advisor = insights.advisorBullets ?? [];
+        if (narrator.length) {
+          lines.push("Insights \u2014 observations:");
+          narrator.forEach((b) => lines.push(`- ${b}`));
+        }
+        if (advisor.length) {
+          lines.push("Insights \u2014 recommendations:");
+          advisor.forEach((b) => lines.push(`- ${b}`));
+        }
+        lines.push("");
+      } else {
+        lines.push("Insights: none generated yet.");
+        lines.push("");
+      }
+      lines.push(`## Data sufficiency: ${dataState.toUpperCase()}`);
+      lines.push(guidanceFor(dataState, contextType));
+      lines.push("");
+      lines.push(`## Best-practice priors (${contextType})`);
+      priorsFor(contextType).forEach((p) => lines.push(`- ${p}`));
+      lines.push("");
+      lines.push("## How to implement (code-native variant)");
+      lines.push(`1. Search the repository for <Adaptive id="${componentId}"> (and any matching useAssignment("${componentId}") usage).`);
+      lines.push('2. Add a new key to its `variants` map with on-brand JSX that matches the surrounding components and the project\'s design system. Pick a short, descriptive new variant id that is not in the existing list above (e.g. "value_led", "social_proof", "urgency").');
+      lines.push("3. If the component is server-rendered via <AdaptiveRoot>, add the new variant id to that component's entry in the `components` list so it is included in SSR preloading.");
+      lines.push("4. Do NOT call create_variant \u2014 that creates a separate no-code MANAGED draft. Code-native variants register automatically on the first assignment after you deploy, and go live immediately.");
+      lines.push("5. Commit, push, and deploy. Optionally enable shadow mode for this component first if you want to validate before serving real traffic.");
+      lines.push("");
+      lines.push("Make the change reflect the data sufficiency above: data-driven when SUFFICIENT, best-practice-led when COLLECTING or EMPTY.");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/test-brief.ts
+import { z as z10 } from "zod";
+var projectIdSchema10 = z10.string().uuid().describe("The project UUID");
+async function settled2(p) {
+  try {
+    return await p;
+  } catch {
+    return null;
+  }
+}
+function registerTestBriefTools(server, client) {
+  server.tool(
+    "get_test_brief",
+    "Get a ready-to-paste test for a SentientUI-wrapped component, populated with the component's real variants and goals. This project uses @sentientui/react/testing. Use this so your tests force a specific variant/layout deterministically and never break when the optimizer serves a different version. Returns a React Testing Library example plus the URL-param recipe for E2E (Playwright/Cypress).",
+    {
+      projectId: projectIdSchema10,
+      componentId: z10.string().describe('The component ID to write a test for (matches <Adaptive id="...">).')
+    },
+    async ({ projectId, componentId }) => {
+      const id = encodeURIComponent(projectId);
+      const [components, goalsRes] = await Promise.all([
+        settled2(client.get(`/projects/${id}/components`)),
+        settled2(client.get(`/projects/${id}/goals`))
+      ]);
+      const component = components?.find((c) => c.component_id === componentId) ?? null;
+      const variantIds = component?.variants.map((v) => v.variant_id) ?? [];
+      const goals = Array.isArray(goalsRes) ? goalsRes : goalsRes?.goals ?? [];
+      const goalName = goals[0]?.goalName ?? "signup";
+      const controlId = variantIds[0] ?? "control";
+      const forcedId = variantIds.find((v) => v !== controlId) ?? "variant_b";
+      const lines = [];
+      lines.push(`# Test brief \u2014 ${componentId}`);
+      lines.push("");
+      lines.push("This project uses **`@sentientui/react/testing`**. By default SentientUI serves the *control* variant and default layout in tests and sends no events, so existing tests are unaffected. Pass a scenario to force a specific variant/layout.");
+      if (!component) {
+        lines.push("");
+        lines.push(`Note: no component named "${componentId}" has reported data yet. If you are adding this \`<Adaptive>\`, that is expected \u2014 the example below uses placeholder variant IDs; replace them with the ones you declare in \`variants={{ \u2026 }}\`.`);
+      }
+      lines.push("");
+      lines.push("## React Testing Library");
+      lines.push("```tsx");
+      lines.push(`import { renderWithSentient } from '@sentientui/react/testing';`);
+      lines.push(`import { screen } from '@testing-library/react';`);
+      lines.push("");
+      lines.push(`test('${componentId}: forces the "${forcedId}" variant', () => {`);
+      lines.push(`  renderWithSentient(<YourPage />, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // assert on the ${forcedId} variant's content:`);
+      lines.push(`  // expect(screen.getByText('\u2026')).toBeInTheDocument();`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## Assert a goal fires (with the mock server)");
+      lines.push("```tsx");
+      lines.push(`import { setupSentientServer } from '@sentientui/react/testing/node';`);
+      lines.push(`import { getSentientEvents, hasFiredGoal } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = setupSentientServer();`);
+      lines.push(`afterAll(() => s.server.close());`);
+      lines.push("");
+      lines.push(`test('${componentId}: fires the ${goalName} goal', async () => {`);
+      lines.push(`  s.use({ variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`  // \u2026render with a live client, trigger the interaction\u2026`);
+      lines.push(`  expect(hasFiredGoal(getSentientEvents(), '${goalName}')).toBe(true);`);
+      lines.push("});");
+      lines.push("```");
+      lines.push("");
+      lines.push("## E2E (Playwright / Cypress)");
+      lines.push(`Use \`mockSentient\` to force variants/layout, stub the API, and capture events:`);
+      lines.push("```ts");
+      lines.push(`import { mockSentient } from '@sentientui/react/testing';`);
+      lines.push("");
+      lines.push(`const s = await mockSentient(page, { variants: { ${componentId}: '${forcedId}' } });`);
+      lines.push(`await page.goto('/');`);
+      lines.push(`expect(s.events().some((e) => e.goalType === '${goalName}')).toBe(true);`);
+      lines.push("```");
+      lines.push(`Cypress: \`mockSentientCypress(cy, scenario)\` in a beforeEach. **Prefer mockSentient in CI \u2014 it writes nothing.**`);
+      lines.push(`The URL param below is fine for a quick local pin, but a live client still creates an (automation-flagged) session:`);
+      lines.push("```ts");
+      lines.push(`await page.goto('/?sentient_variant=${componentId}:${forcedId}');`);
+      lines.push("```");
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
+// src/tools/integration-guide.ts
+var GUIDE = `# SentientUI integration guide \u2014 the adaptive ladder
+
+SentientUI adapts a site per visitor type (personas: buyer, researcher, deal_seeker, browser,
+unknown), learning from real conversions. Decisions are locked per session: Visit 1 learns,
+Visit 2 converts. Integrate one rung at a time.
+
+## Setup (60 seconds, no account)
+
+1. Run \`npx @sentientui/cli init\` (detects Next App/Pages, Vite, Remix, CRA; installs
+   @sentientui/react; wraps the app; writes .env.local; scaffolds an example).
+2. \`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).
+3. To learn from real traffic: create a project at https://sentient-ui.com and set
+   NEXT_PUBLIC_SENTIENT_API_KEY=pk_... in .env.local.
+
+Manual setup: 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.
+
+## Rung 1 \u2014 Style (CSS only)
+
+Persona attributes on <html> (zero declaration):
+
+    html[data-sentient-persona='deal_seeker'] .discount-banner { display: block; }
+    html[data-sentient-confidence='low'] .discount-banner { display: none; }
+
+Learned style tokens (element-scoped, SSR-safe):
+
+    const t = useAdaptiveTokens('hero', {
+      tone: ['calm', 'urgent'],   // first value = baseline
+    });
+    return <section {...t.props} className="hero">\u2026</section>;
+    // CSS: .hero[data-tone='urgent'] .cta { font-weight: 700; }
+
+Rules: 1-4 dims, 2-6 values each, enum values only. For animation values, always add a
+prefers-reduced-motion: reduce override in CSS.
+
+## Rung 2 \u2014 Swap (alternate content)
+
+    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.
+
+## Rung 3 \u2014 Reorder (structure)
+
+    <AdaptiveGroup id="pricing-area" arrangements={{
+      standard:     ['plans', 'faq', 'social'],   // first key = baseline
+      social_first: ['social', 'plans', 'faq'],
+    }}>
+      <PlanGrid key="plans"/> <Faq key="faq"/> <Testimonials key="social"/>
+    </AdaptiveGroup>
+
+Declared orders of keyed children only. Page-level: sections={[...]} on AdaptiveRoot +
+useLayoutOrder().
+
+## Testing the integration
+
+Use '@sentientui/react/testing': renderWithSentient(ui, { variants, slots, persona }) forces
+deterministic outcomes so tests never depend on what the optimizer serves.
+`;
+function registerIntegrationGuideTools(server) {
+  server.tool(
+    "get_integration_guide",
+    "Get the SentientUI adaptive-ladder integration guide: setup (keyless and keyed) plus copy-pasteable examples for every rung (Style, Swap, Reorder). Use this to integrate SentientUI into a codebase.",
+    {},
+    async () => ({ content: [{ type: "text", text: GUIDE }] })
+  );
+}
+
 // src/server.ts
 function createMcpServer(client) {
   const server = new McpServer({
@@ -326,7 +657,10 @@ function createMcpServer(client) {
   registerGoalTools(server, client);
   registerGuardrailTools(server, client);
   registerLayoutTools(server, client);
+  registerVariantBriefTools(server, client);
+  registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
+  registerIntegrationGuideTools(server);
   return server;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "type": "module",
   "bin": {
@@ -21,13 +21,6 @@
     "README.md",
     "AGENTS.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsx src/index.ts",
-    "prepublishOnly": "pnpm build && pnpm typecheck"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -41,5 +34,11 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts"
   }
-}
+}