@apex-inc/mcp-server 0.32.0 → 0.34.0

package/dist/tools/experiments.js

@@ -0,0 +1,2090 @@
+import { z } from "zod";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { apiGet, apiPost, apiPatch, apiDelete, getActiveWorkspace, } from "../api-client.js";
+import { resolveExperimentHypothesis } from "../experiment-copy.js";
+import { activationLiveLine, shouldRefuseActivationWiring } from "../activation-wiring.js";
+import { fetchLiveTestHits, formatLiveTestStop, isFileStop, isObjectStop, } from "../live-test-guard.js";
+import { hasConflictAdvisory, renderConflictAdvisory, } from "../conflict-advisory.js";
+import { APEX, controlPctOf, daysRunningOf, findVariant, formatArmLine, titleCaseEvent, assertTargetUrlForActiveWorkspace, errMsg, resolveCreateSurface, } from "../tool-shared.js";
+export const experimentTools = {
+    plan_experiment: {
+        description: `${APEX} — PLANNING ONLY, does not create anything. Analyzes a goal against existing beliefs and experiments, then returns structured options for the user to choose from. After calling, you MUST present the returned options as a numbered list or poll and wait for the user to pick before calling any other Apex tools.`,
+        schema: z.object({
+            goal: z.string().describe("What the user wants to improve or test (e.g. 'improve signup conversion on landing page')"),
+            targetUrl: z.string().optional().describe("URL of the page to test, if known"),
+        }),
+        handler: async ({ goal, targetUrl }) => {
+            const [beliefs, experiments] = await Promise.all([
+                apiGet("/api/beliefs"),
+                apiGet("/api/experiments?unified=true"),
+            ]);
+            const keywords = goal
+                .toLowerCase()
+                .replace(/[^a-z0-9\s]/g, "")
+                .split(/\s+/)
+                .filter((w) => w.length > 3);
+            const relatedBeliefs = beliefs.filter((b) => {
+                const words = b.statement.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const relatedExperiments = experiments.filter((e) => {
+                const words = e.name.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const plan = {
+                _apex: true,
+                goal,
+                targetUrl: targetUrl || null,
+                relatedBeliefs: relatedBeliefs.slice(0, 5).map((b) => ({
+                    id: b.id,
+                    statement: b.statement,
+                    confidence: Math.round(b.confidence * 100),
+                    tested: experiments.some((e) => e.beliefId === b.id),
+                })),
+                relatedExperiments: relatedExperiments.slice(0, 3).map((e) => ({
+                    id: e.id,
+                    name: e.name,
+                    status: e.status,
+                })),
+                suggestedBeliefs: [
+                    `Users who see [specific change] will convert at a higher rate`,
+                    `The current [element] is the primary friction point for [goal]`,
+                    `A clearer value proposition will reduce bounce rate`,
+                ],
+                suggestedMetrics: [
+                    "signup_conversion_rate",
+                    "bounce_rate",
+                    "click_through_rate",
+                    "time_on_page",
+                ],
+                suggestedConfidenceLevels: [
+                    { label: "Low (30%) — Gut feeling, no supporting data yet", value: 30 },
+                    { label: "Medium (55%) — Some signals, but hasn't been tested", value: 55 },
+                    { label: "High (75%) — Strong evidence from past experiments or data", value: 75 },
+                    { label: "Very High (90%) — Near-certain, well-established pattern", value: 90 },
+                ],
+                suggestedTrafficAllocations: [
+                    { label: "Adaptive (recommended) — Automatically shifts traffic toward the winning variant", control: 50, variant: 50, adaptive: true },
+                    { label: "Balanced 50/50 — Equal split, fastest to reach significance", control: 50, variant: 50, adaptive: false },
+                    { label: "Conservative 80/20 — Minimal exposure to variant, lower risk", control: 80, variant: 20, adaptive: false },
+                ],
+                _instructions: "IMPORTANT: Present each section as a numbered selection the user can pick from. Use a poll or numbered list for beliefs, confidence, metrics, and traffic split. Do NOT auto-fill any values.",
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(plan, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    start_reasoning: {
+        description: `${APEX} — Record a belief and hypothesis chain. Only call AFTER the user has picked a belief statement and confidence level from the options you presented.`,
+        schema: z.object({
+            decision: z.string().describe("What you want to improve or change"),
+            belief: z.string().describe("The assumption — must be confirmed by the user"),
+            confidence: z
+                .number()
+                .min(0)
+                .max(100)
+                .describe("How sure the user is about this assumption (0-100%) — must be chosen by the user"),
+        }),
+        handler: async ({ decision, belief, confidence }) => {
+            const b = await apiPost("/api/beliefs", {
+                statement: belief,
+                confidence: confidence / 100,
+            });
+            const hypothesis = `If we act on "${belief.slice(0, 80)}", then we should see a measurable improvement in our target metric.`;
+            const h = await apiPost("/api/hypotheses", {
+                beliefId: b.id,
+                statement: hypothesis,
+                predictedEffect: `Impact related to: ${decision.slice(0, 60)}`,
+                confidence: confidence / 100,
+                status: "active",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Belief recorded`,
+                            ``,
+                            `  ID: ${b.id}`,
+                            `  Statement: "${b.statement}"`,
+                            `  Confidence: ${Math.round(b.confidence * 100)}%`,
+                            `  Hypothesis: ${h.id}`,
+                            ``,
+                            `Present the user with these next steps as selections:`,
+                            `  1. Log a prediction — how much impact do you expect?`,
+                            `  2. Design the experiment — what should we change?`,
+                            `  3. Adjust the belief — refine the assumption first`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    create_belief: {
+        description: `${APEX} — Record an assumption your team is making. Confirm the belief statement and confidence with the user before calling.`,
+        schema: z.object({
+            statement: z.string().describe("The assumption statement"),
+            confidence: z.number().min(0).max(100).describe("How sure you are (0-100%)"),
+            parentBeliefId: z.string().optional().describe("ID of a parent assumption, if this is a sub-assumption"),
+        }),
+        handler: async ({ statement, confidence, parentBeliefId }) => {
+            const b = await apiPost("/api/beliefs", {
+                statement,
+                confidence: confidence / 100,
+                parentBeliefId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${APEX} Assumption tracked [${b.id}]: "${b.statement}" at ${Math.round(b.confidence * 100)}% certainty.`,
+                    },
+                ],
+            };
+        },
+    },
+    create_experiment: {
+        description: `${APEX} — Create an experiment record. Returns a structured recipe for the AI agent to implement. The agent makes the actual code changes using useApexVariant hook — Apex never generates code. Always call with preview=true first so the user sees a summary.`,
+        schema: z.object({
+            name: z.string().describe("Experiment name"),
+            targetUrl: z.string().describe("URL of the page to test on the ACTIVE workspace (include #anchor for section targeting). Must be a host this workspace has actually sent events from — never guess a brand domain or a sibling workspace's site."),
+            controlContent: z.string().describe("The current content that the control shows"),
+            variantContent: z.string().describe("The new content for the variant"),
+            targetComponent: z.string().optional().describe("Component or file path where the change should be made"),
+            targetAnchor: z.string().optional().describe("Section anchor/ID on the page (e.g. 'pricing', 'hero')"),
+            trafficSplit: z.number().min(1).max(99).optional().describe("Percentage of traffic to control (default 50)"),
+            beliefId: z.string().optional().describe("ID of the assumption this tests"),
+            hypothesisId: z.string().optional().describe("ID of the expected outcome"),
+            predictionId: z.string().optional().describe("ID of the expected impact"),
+            beliefStatement: z.string().optional().describe("If you don't have a beliefId, pass the assumption statement and Apex will create the belief (and a hypothesis) and link them to this experiment."),
+            beliefConfidence: z.number().min(0).max(100).optional().describe("Confidence (0-100%) for the belief created from beliefStatement. Defaults to 50."),
+            hypothesisStatement: z.string().optional().describe("Optional hypothesis statement to record alongside a belief created from beliefStatement."),
+            primaryMetricEvent: z.string().optional().describe("Canonical event name the experiment optimizes, e.g. 'add_to_cart', 'checkout_completed', 'form_submit'. Validated against the workspace event spec. Prefer an OUTCOME event (purchase/signup) over a proxy (email_open) — use list_metrics to see which are DETECTED with volume."),
+            primaryMetricType: z.enum(["rate", "count", "revenue", "duration"]).optional().describe("How the goal is measured. 'rate' (default) = did it happen. 'revenue'/'duration' = a continuous value summed per subject (set primaryMetricValueProperty). Use 'revenue' for Stripe/purchase-value goals."),
+            primaryMetricValueProperty: z.string().optional().describe("For revenue/duration goals: the event property to sum, e.g. 'value'. Defaults to 'value'."),
+            guardrailEvent: z.string().optional().describe("Canonical protective event for an EXTRA guardrail that must not regress (e.g. 'purchase_refunded', 'app_uninstall', 'js_error'). Apex already auto-protects revenue/refunds/errors by default — only pass this to add a test-specific harm signal. Use list_metrics({role:'guardrail'}) to see what's firing. Choose one ORTHOGONAL to the primary goal."),
+            guardrailType: z.enum(["rate", "revenue", "duration"]).optional().describe("How the guardrail is measured. 'rate' (default) = how often the harm event fires. 'revenue' = sum a value (e.g. refund $)."),
+            guardrailThreshold: z.number().optional().describe("Harm margin for the guardrail, RELATIVE (0.25 = flag a >25% rise). Defaults to 0.25."),
+            predictionMagnitude: z.string().optional().describe("Your committed prediction of the effect, e.g. '10% lift'. Recorded with 'agent' provenance and used for calibration. Required before the experiment can be ACTIVATED."),
+            surface: z.enum(["web", "mobile"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' for a website, 'mobile' for a native / Capacitor / React-Native app. OPTIONAL — when omitted it is auto-detected from repo signals (capacitor.config.* / @apex-inc/capacitor-plugin → mobile) and the workspace's registered data sources; pass it explicitly only to override or when both web and mobile sources exist. Sets the dashboard data-source label (Website vs Mobile app)."),
+            dataSourceId: z.string().optional().describe("Optional explicit Data Source (property) id this experiment runs in, e.g. 'ds_website' or 'ds_ios'. Usually inferred from surface; pass it to bind to a specific registered source. Tenant-validated server-side."),
+            randomizationUnit: z.enum(["device", "visitor", "person", "account", "org"]).optional().describe("What to bucket on. Default 'visitor' (per-device). Use 'person' to give one stitched user the same variant across their devices, or 'account'/'org' for B2B account-level tests where everyone in an account should see the same variant."),
+            minSamplePerArm: z.number().int().min(30).optional().describe("Minimum exposed subjects PER ARM before a winner can be claimed (the sample gate). Defaults to 50. Raise it to demand more evidence (detect a smaller lift); lower it (floor 30) for low-traffic properties that would otherwise stall. The real winner-gate is still the 95% probability-to-be-best — this only sets the traffic floor. Pre-registration: frozen once the experiment is running."),
+            runtimeDays: z.number().int().min(1).max(365).optional().describe("How long to run the experiment, in days (the decision window). Apex force-concludes at this point — decisive winner if reached, else inconclusive. Defaults to 14. Set e.g. 28 to run for four weeks. This is the max runtime, not a minimum: a decisive winner can conclude sooner. Pre-registration: frozen once the experiment is running (fork to change it)."),
+            preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
+        }),
+        handler: async (args) => {
+            const targetCheck = await assertTargetUrlForActiveWorkspace(args.targetUrl);
+            if (!targetCheck.ok) {
+                return {
+                    content: [{ type: "text", text: `${APEX} ${targetCheck.message}` }],
+                    isError: true,
+                };
+            }
+            const split = args.trafficSplit ?? 50;
+            // MCP experiments are ALWAYS code-native (SDK). Client-side snippet /
+            // runtime-DOM experiments are intentionally NOT offered here (founder
+            // decision 2026-07-05): the MCP audience is developers in an IDE with the
+            // code open, where `useApexVariant` branches in React (can change
+            // anything, needs a deploy, no fragile selectors, deterministic
+            // exposure). First HTML is flicker-free only when the merchant app
+            // assigns on the document request and passes that arm in. MCP does
+            // not serve the visitor page. Snippet experiments live in the Apex
+            // web app's visual editor for the no-code / non-repo case.
+            const mode = "sdk";
+            // Surface auto-detect (QA 2026-06-18): when the agent doesn't pass a
+            // surface, infer it from repo signals + registered data sources instead of
+            // silently defaulting to web (which mislabels mobile apps). Ambiguous →
+            // ask the agent to choose.
+            const surfaceResolution = await resolveCreateSurface(args.surface);
+            if ("ambiguous" in surfaceResolution) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} This workspace has both web and mobile data sources — pass surface ("web" or "mobile") explicitly so the experiment is labeled and grouped correctly.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const experimentSurface = surfaceResolution.surface;
+            const isPreview = args.preview !== false;
+            // p1-metric — resolve the primary metric (the conversion goal).
+            //
+            // Founder decision 2026-07-05: DO NOT silently default the conversion
+            // event to `form_submit`. A guessed goal ("Signups" that secretly counts
+            // form submits) is worse than none. When the caller doesn't name a
+            // conversion event, the draft is created UNWIRED (no `source`): it's a
+            // valid draft, but the activation gate blocks starting it until a real
+            // outcome event is set — and we nudge loudly to set one. An explicit
+            // primaryMetricEvent is validated against the workspace event spec.
+            const conversionEventSet = Boolean(args.primaryMetricEvent);
+            let primaryMetric = {
+                key: "conversion_goal",
+                label: "Conversion goal (not set)",
+                type: "rate",
+                unit: "%",
+                direction: "increase",
+                // No `source` — UNWIRED on purpose. Can't start until set.
+            };
+            if (args.primaryMetricEvent) {
+                const event = args.primaryMetricEvent.trim();
+                let validEvents = [];
+                try {
+                    const spec = await apiGet("/api/spec/events");
+                    validEvents = Object.keys(spec.data?.events ?? {});
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Could not load the event spec to validate primaryMetricEvent "${event}" (${message}). Fix the connection, or omit primaryMetricEvent to create the draft without a conversion goal (you'll set it before starting).`,
+                            }],
+                        isError: true,
+                    };
+                }
+                if (validEvents.length && !validEvents.includes(event)) {
+                    const sample = validEvents.slice(0, 12).join(", ");
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `"${event}" is not a canonical event in this workspace's event spec. Valid options include: ${sample}${validEvents.length > 12 ? ", …" : ""}. Use get_event_spec for the full list.`,
+                            }],
+                        isError: true,
+                    };
+                }
+                const metricType = args.primaryMetricType ?? "rate";
+                const isValue = metricType === "revenue" || metricType === "duration";
+                const valueProperty = args.primaryMetricValueProperty ?? "value";
+                primaryMetric = {
+                    key: `${event}_${metricType}`,
+                    label: `${titleCaseEvent(event)} ${metricType}`,
+                    type: metricType,
+                    unit: metricType === "revenue" ? "USD" : metricType === "duration" ? "s" : "%",
+                    direction: "increase",
+                    source: isValue
+                        ? { kind: "event", eventType: event, property: valueProperty }
+                        : { kind: "event", eventType: event },
+                };
+            }
+            if (isPreview) {
+                // Author-time conflict guard (best-effort, non-blocking): warn if this
+                // overlaps a LIVE experiment on the same surface before it's created.
+                let conflictAdvisory;
+                try {
+                    const cc = await apiPost("/api/experiments/check-conflicts", {
+                        surface: experimentSurface,
+                        target_component: args.targetComponent,
+                        target_url: args.targetUrl,
+                        target_anchor: args.targetAnchor,
+                        data_source_id: args.dataSourceId,
+                        primary_metric_event: primaryMetric.source?.eventType,
+                    });
+                    if (hasConflictAdvisory(cc.data)) {
+                        conflictAdvisory = renderConflictAdvisory(cc.data);
+                    }
+                }
+                catch {
+                    /* conflict check is advisory; never block the preview */
+                }
+                const recipe = {
+                    _apex: true,
+                    _type: "experiment_preview",
+                    name: args.name,
+                    surface: experimentSurface,
+                    targetUrl: args.targetUrl,
+                    targetAnchor: args.targetAnchor || null,
+                    targetComponent: args.targetComponent || null,
+                    mode,
+                    trafficSplit: { control: split, variant: 100 - split },
+                    decisionWindowDays: args.runtimeDays ?? 14,
+                    minSamplePerArm: args.minSamplePerArm ?? 50,
+                    control: args.controlContent,
+                    variant: args.variantContent,
+                    conversionGoal: conversionEventSet
+                        ? { event: primaryMetric.source?.eventType, type: primaryMetric.type }
+                        : "NOT SET — required before the experiment can start",
+                    beliefId: args.beliefId || null,
+                    beliefStatement: args.beliefStatement || null,
+                    predictionId: args.predictionId || null,
+                    ...(conflictAdvisory ? { _conflict_advisory: conflictAdvisory } : {}),
+                    ...(conversionEventSet
+                        ? {}
+                        : {
+                            _conversion_goal_warning: "No conversion event set. The draft will be created, but it CANNOT be started until you set the outcome you're optimizing. Call list_events to see what's firing (prefer a real outcome like signup/purchase over form_submit), then pass primaryMetricEvent. Confirm the goal with the user before creating.",
+                        }),
+                    _instructions: `Before proposing variant copy, ground every factual claim in .apex/brand-truth.md (read it; cite the line each claim traces to; if a claim isn't backed there, ask the user instead of inventing it).${conflictAdvisory ? " IMPORTANT: _conflict_advisory is set — show it to the user and resolve the overlap (mutex / variant / sequence) before creating." : ""}${conversionEventSet ? "" : " IMPORTANT: _conversion_goal_warning is set — surface it and set a conversion event (list_events → primaryMetricEvent) before creating, unless the user explicitly wants a draft to fill in later."} Then present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.`,
+                };
+                return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+            }
+            // p2-linking — if the caller passed a belief statement instead of a
+            // pre-created beliefId, create the belief + hypothesis (mirroring
+            // start_reasoning) and link them to this experiment.
+            let beliefId = args.beliefId;
+            let hypothesisId = args.hypothesisId;
+            if (!beliefId && args.beliefStatement) {
+                const confidence = args.beliefConfidence != null ? args.beliefConfidence / 100 : 0.5;
+                const b = await apiPost("/api/beliefs", {
+                    statement: args.beliefStatement,
+                    confidence,
+                });
+                beliefId = b.id;
+                const hypothesisStatement = args.hypothesisStatement ??
+                    `If we act on "${args.beliefStatement.slice(0, 80)}", then we should see a measurable improvement in "${args.name}".`;
+                const h = await apiPost("/api/hypotheses", {
+                    beliefId: b.id,
+                    statement: hypothesisStatement,
+                    predictedEffect: `Impact related to: ${args.name.slice(0, 60)}`,
+                    confidence,
+                    status: "active",
+                });
+                hypothesisId = h.id;
+            }
+            // The API requires a non-empty hypothesis on the experiment record
+            // (validate-create rejects ""). Resolve one (explicit or derived).
+            const resolvedHypothesis = resolveExperimentHypothesis(args.hypothesisStatement, args.name, primaryMetric.label);
+            const controlW = split / 100;
+            const createdAtIso = new Date().toISOString();
+            // Variants must match the experiment surface (validate-create enforces
+            // this). Web arms carry DOMChange[]; mobile arms carry a JSON payload the
+            // app reads via Apex.getVariant(). Mislabeling a Capacitor app as web is
+            // exactly the bug this fixes.
+            const variants = experimentSurface === "mobile"
+                ? [
+                    {
+                        id: "v_control",
+                        key: "control",
+                        label: "Control",
+                        surface: "mobile",
+                        createdAt: createdAtIso,
+                        description: "Original content",
+                        payload: { content: args.controlContent },
+                    },
+                    {
+                        id: "v_a",
+                        key: "variant_a",
+                        label: "Variant A",
+                        surface: "mobile",
+                        createdAt: createdAtIso,
+                        description: "Modified content",
+                        payload: { content: args.variantContent },
+                    },
+                ]
+                : [
+                    {
+                        id: "v_control",
+                        key: "control",
+                        label: "Control",
+                        surface: "web",
+                        mode,
+                        createdAt: createdAtIso,
+                        description: "Original content",
+                        changes: [],
+                    },
+                    {
+                        id: "v_a",
+                        key: "variant_a",
+                        label: "Variant A",
+                        surface: "web",
+                        mode,
+                        createdAt: createdAtIso,
+                        description: "Modified content",
+                        changes: [
+                            {
+                                selector: "*",
+                                type: "text",
+                                value: args.variantContent,
+                                originalValue: args.controlContent,
+                            },
+                        ],
+                    },
+                ];
+            const exp = await apiPost("/api/experiments", {
+                surface: experimentSurface,
+                name: args.name,
+                targetUrl: args.targetUrl,
+                targetAnchor: args.targetAnchor,
+                // Persist the component (e.g. "ProductCard") as a precise location
+                // signal for the author-time conflict guard — esp. mobile/SDK arms.
+                ...(args.targetComponent ? { targetComponent: args.targetComponent } : {}),
+                createdFrom: "cursor",
+                status: "draft",
+                ...(args.dataSourceId ? { dataSourceId: args.dataSourceId } : {}),
+                ...(args.randomizationUnit ? { randomizationUnit: args.randomizationUnit } : {}),
+                // Sample-size floor (minPerVariant) and/or run duration (durationDays).
+                // The API merges evaluationWindow, so sending one never clobbers the other.
+                ...(() => {
+                    const ew = {};
+                    if (args.minSamplePerArm)
+                        ew.minPerVariant = args.minSamplePerArm;
+                    if (args.runtimeDays)
+                        ew.durationDays = args.runtimeDays;
+                    return Object.keys(ew).length > 0 ? { evaluationWindow: ew } : {};
+                })(),
+                hypothesis: resolvedHypothesis,
+                // Agent-authored: tagged "agent" provenance so calibration attributes it
+                // correctly. When the agent supplies predictionMagnitude it satisfies the
+                // activation gate; an empty magnitude leaves the gate asking for one.
+                prediction: {
+                    direction: "increase",
+                    magnitude: args.predictionMagnitude?.trim() ?? "",
+                    provenance: "agent",
+                },
+                confidence: 50,
+                beliefId,
+                hypothesisId,
+                predictionId: args.predictionId,
+                primaryMetric,
+                allocation: { strategy: "hash", weights: { control: controlW, variant_a: 1 - controlW } },
+                secondaryMetrics: [],
+                // Explicit EXTRA guardrail when the agent named one (orthogonal to the
+                // goal). When omitted, the server auto-attaches the conversion-model
+                // vital signs ("protected by default").
+                ...(args.guardrailEvent
+                    ? {
+                        guardrailMetrics: [
+                            (() => {
+                                const gType = args.guardrailType ?? "rate";
+                                const isValue = gType === "revenue" || gType === "duration";
+                                return {
+                                    key: `${args.guardrailEvent}_${gType}`,
+                                    label: `${titleCaseEvent(args.guardrailEvent)} ${gType === "rate" ? "rate" : gType}`,
+                                    type: gType,
+                                    unit: gType === "revenue" ? "USD" : gType === "duration" ? "s" : "%",
+                                    direction: "decrease",
+                                    source: isValue
+                                        ? { kind: "event", eventType: args.guardrailEvent, property: "value" }
+                                        : { kind: "event", eventType: args.guardrailEvent },
+                                    guardrailThreshold: args.guardrailThreshold ?? 0.25,
+                                    thresholdKind: "relative",
+                                };
+                            })(),
+                        ],
+                    }
+                    : {}),
+                // VJATTR D1: 7-day exposure→conversion attribution window (was 24h).
+                attributionWindow: { unit: "days", value: 7, startFrom: "first_interaction" },
+                variants,
+            });
+            let previewUrl = "";
+            try {
+                const vu = new URL(exp.targetUrl || args.targetUrl);
+                vu.searchParams.set("_apex_preview", "variant_a");
+                vu.searchParams.set("_apex_exp", exp.id);
+                if (args.targetAnchor)
+                    vu.hash = args.targetAnchor;
+                previewUrl = vu.toString();
+            }
+            catch { /* non-critical */ }
+            const isMobile = experimentSurface === "mobile";
+            // Grounding guidance — prepended to every recipe. The agent must write
+            // variant copy against the merchant's brand-truth file, not invent
+            // claims (the 2026-06-15 "free shipping on every order" incident, where
+            // the app actually charges $8 under $100).
+            const groundingGuidance = [
+                "GROUND THE COPY — do this BEFORE writing any variant text:",
+                "- Read .apex/brand-truth.md, .apex/brand-voice.md, and .apex/lexicon.md if they exist in the repo.",
+                "- Every factual claim in the variant copy MUST trace to a specific line in .apex/brand-truth.md. State which line each claim comes from. If a claim isn't backed there, ASK the user — do NOT invent it.",
+                "- If .apex/brand-truth.md is missing, scaffold the guardrails first (Apex → Set up Apex → Intelligence → \"Set up experiment guardrails\"), then ask the user to fill in the facts before writing copy.",
+                "",
+            ];
+            // Style/visual-change guidance — appended to every SDK recipe. The
+            // classic failure (QA 2026-06-15): a `bg-black` class collided with
+            // `bg-primary` because the codebase's cn() doesn't tailwind-merge, so
+            // both arms rendered identical and the test measured nothing.
+            const styleGuidance = [
+                "",
+                "VISUAL / STYLE CHANGES — read before editing:",
+                "- If the change is visual (color, size, layout), a variant that renders identical to control measures NOTHING. Always visually diff the two arms (screenshot both) before activating.",
+                "- Do NOT rely on a utility CLASS to override an existing one unless the codebase uses tailwind-merge. Plain className concatenation keeps BOTH classes (e.g. `bg-primary` + `bg-black`) and the original usually wins. Prefer an inline `style={{...}}` override or a class with guaranteed precedence.",
+                "- Change exactly ONE thing (the variable under test); keep everything else identical to control.",
+            ];
+            const webSteps = [
+                "IMPLEMENT THE EXPERIMENT IN CODE (web):",
+                `1. Open the target file${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
+                `2. Install: npm install @apex-inc/next @apex-inc/react`,
+                `3. Add: import { useApexVariant } from "@apex-inc/react"`,
+                `4. In the component, add: const variant = useApexVariant("${exp.id}")  // fires experiment_exposure automatically`,
+                `   Then branch in React. That hook is not flicker-free by itself.`,
+                `   FIRST HTML / FLICKER: first HTML is flicker-free ONLY when it is already the assigned arm.`,
+                `   - SSR (Next, Remix): on the document request, mint or read the apex_vid cookie, assign with the same rules as GET /api/experiments/${exp.id}/assign, and pass that arm: useApexVariant("${exp.id}", { initialVariant, search }) or <ApexProvider assignments={{ "${exp.id}": variant }}>. { search } also makes _apex_preview match on first HTML.`,
+                `   - If you use Next.js: npm install @apex-inc/next @apex-inc/react, then apexVisitorMiddleware, assignExperiments, <ApexProvider assignments>. The hook alone is not flicker-free.`,
+                `   - Client-only SPA: the hook cannot know the arm before first HTML. Do not promise no flicker.`,
+                `   - Snippet mode (Apex mutates the DOM) is a different path. Do not conflate. Do not hide the page until /assign returns (worse LCP). That is not the React-hook promise.`,
+                `   - This MCP call does not serve the visitor page. create_experiment / activate_experiment do not remove flicker. The merchant app must pass the server arm.`,
+                `   - Pass the server arm into the hook or provider. @apex-inc/react accepts initialVariant and ApexProvider assignments.`,
+                `5. Wrap the target content in a conditional (fall back to control on null/error):`,
+                `   {variant === "variant_a" || variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
+                `6. Screenshots for the dashboard — REQUIRED before you tell the user the draft is ready:`,
+                `   - This is an SDK experiment. The variant exists only in local code until it ships.`,
+                `   - Apex does NOT auto-capture a public URL on create (that page does not have the variant yet, and a guessed host shows the wrong site on both arms).`,
+                `   - Capture BOTH arms on localhost with ?_apex_preview=control|variant_a&_apex_exp=${exp.id}, then call attach_experiment_asset({experimentId, variantKey, imageBase64}) for each arm.`,
+                `   - After the code is deployed, recapture_experiment_screenshots refreshes the live host.`,
+                `7. Show the user the diff. Dashboard "View live" links are built from target_url (not a hardcoded host). Preview the variant at: ${previewUrl}`,
+                `   If the merchant is QA'ing on localhost, the dashboard rewrites Apex app hosts to this origin so the unpublished variant is visible.`,
+                `8. After preview approval, commit and push`,
+                `9. Call track_deployment with the experiment ID and commit SHA`,
+                `10. Call activate_experiment (with the user's go-ahead). If the code isn't live yet, the`,
+                `    experiment holds in "Waiting on deploy" and starts automatically at the first exposure —`,
+                `    verify with verify_experiment_wiring after the deploy lands.`,
+            ];
+            const mobileSteps = [
+                "IMPLEMENT THE EXPERIMENT IN CODE (mobile / Capacitor):",
+                `1. Open the target screen${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
+                `2. Install the plugin: npm i @apex-inc/capacitor-plugin`,
+                `3. Add: import { Apex } from "@apex-inc/capacitor-plugin"`,
+                `4. Resolve the variant: const { value: variant } = await Apex.getVariant({ experimentId: "${exp.id}" })  // fires experiment_exposure automatically`,
+                `5. Render conditionally (fall back to control on null/error): variant === "variant_a" || variant === "variant_b" ? <VARIANT> : <CONTROL>`,
+                `6. Screenshot both arms — add ONE debug-gated line on the screen that renders the variant, keyed to the resolved variant so it fires once the arm is on-screen:`,
+                `       useEffect(() => { if (variant) Apex.captureVariantScreenshot({ experimentId: "${exp.id}", variantKey: variant }); }, [variant]);`,
+                `   It is debug-gated (init Apex with debug:true) — a no-op in production, so real users are never screenshotted.`,
+                `7. Show the user the diff and a side-by-side of both arms`,
+                `8. After approval, commit and push`,
+                `9. Call track_deployment with the experiment ID and commit SHA`,
+                `10. Call verify_experiment_wiring, then activate_experiment once both arms report exposures`,
+            ];
+            // Autonomous-agent activation policy (Phase 6): the experiment is created
+            // as a DRAFT. Activating it spends metered usage and exposes real users,
+            // so an agent must NOT auto-activate — surface the cost and get explicit
+            // human approval first. The server's activation gate also independently
+            // requires the full spine (measurable goal + guardrail + prediction).
+            const activationPolicy = [
+                "",
+                "ACTIVATION POLICY — do not auto-activate:",
+                "- This experiment is a DRAFT. It is NOT collecting data yet.",
+                "- Activating meters usage (one billable orchestration per variant assignment) and shows variants to real users.",
+                "- Before calling activate_experiment, tell the user the expected metered volume and get their explicit go-ahead.",
+                "- Activation also requires a measurable primary goal, a guardrail, and a committed prediction (the server enforces this). If you didn't pass predictionMagnitude, add one first.",
+            ];
+            const conversionGoalNudge = conversionEventSet
+                ? []
+                : [
+                    "",
+                    "⚠️ CONVERSION GOAL NOT SET — this draft cannot be started yet:",
+                    "- No outcome event is wired, so there's nothing to measure a winner on.",
+                    "- Pick the real outcome: call list_events to see what's firing in this",
+                    "  workspace, then update_experiment({ experiment_id, primary_metric_event }).",
+                    "- Prefer a true outcome (signup / purchase / checkout_completed) over a",
+                    "  proxy like form_submit. Confirm the goal with the user.",
+                    "- activate_experiment will refuse until a measurable goal is set.",
+                ];
+            const recipe = {
+                _apex: true,
+                _type: "experiment_created",
+                experimentId: exp.id,
+                name: exp.name,
+                surface: experimentSurface,
+                status: exp.status,
+                mode,
+                conversionGoal: conversionEventSet
+                    ? { event: primaryMetric.source?.eventType, type: primaryMetric.type }
+                    : "NOT SET — required before start (see _instructions)",
+                decisionWindowDays: args.runtimeDays ?? 14,
+                minSamplePerArm: args.minSamplePerArm ?? 50,
+                beliefId: beliefId || null,
+                hypothesisId: hypothesisId || null,
+                predictionId: args.predictionId || null,
+                sdk: mode === "sdk" ? {
+                    ...(isMobile
+                        ? {
+                            method: "Apex.getVariant",
+                            import: "@apex-inc/capacitor-plugin",
+                            install: "npm i @apex-inc/capacitor-plugin",
+                        }
+                        : {
+                            hook: "useApexVariant",
+                            import: "@apex-inc/react",
+                            install: "npm install @apex-inc/next @apex-inc/react",
+                        }),
+                    experimentId: exp.id,
+                    targetComponent: args.targetComponent || null,
+                    targetAnchor: args.targetAnchor || null,
+                    control: args.controlContent,
+                    variant: args.variantContent,
+                } : null,
+                previewUrl,
+                trafficSplit: { control: split, variant: 100 - split },
+                // Always code-native (SDK) — see the `mode` note above.
+                _instructions: groundingGuidance
+                    .concat(isMobile ? mobileSteps : webSteps)
+                    .concat(styleGuidance)
+                    .concat(activationPolicy)
+                    .concat(conversionGoalNudge)
+                    .join("\n"),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    attach_experiment_asset: {
+        description: `${APEX} — Attach a variant screenshot to an experiment. Use after capturing a control/variant screenshot: for localhost or auth-gated pages the agent captures, pass imageBase64; for an already-hosted image, pass url. The stored asset shows on the dashboard experiment card and the experiment detail gallery.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to attach the screenshot to"),
+            variantKey: z.string().describe("control | variant_b | …"),
+            imageBase64: z.string().optional().describe("Base64-encoded PNG/JPEG. For localhost/auth-gated pages captured by the agent."),
+            url: z.string().url().optional().describe("Already-hosted public image URL."),
+            viewport: z.enum(["desktop", "tablet", "mobile"]).optional().describe("Viewport the screenshot was captured at (default desktop)."),
+            format: z.enum(["png", "jpeg"]).optional().describe("Image format (default png)."),
+            label: z.string().optional().describe("Optional caption for the asset."),
+            commitSha: z.string().optional().describe("Optional commit SHA the screenshot corresponds to."),
+        }),
+        handler: async (args) => {
+            if (!args.imageBase64 && !args.url) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Provide either imageBase64 (for localhost/auth-gated captures) or url (an already-hosted image).",
+                        }],
+                    isError: true,
+                };
+            }
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(args.experimentId)}/assets`, {
+                variantKey: args.variantKey,
+                source: "agent",
+                viewport: args.viewport ?? "desktop",
+                imageBase64: args.imageBase64,
+                url: args.url,
+                format: args.format ?? "png",
+                label: args.label,
+                commitSha: args.commitSha,
+            });
+            const asset = res.data;
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `${APEX} Screenshot attached to experiment ${args.experimentId}`,
+                            ``,
+                            `  Variant: ${asset.variantKey}`,
+                            `  Viewport: ${asset.viewport}`,
+                            `  Stored at: ${asset.url}`,
+                            ``,
+                            `It now shows on the dashboard experiment card and the experiment detail gallery.`,
+                        ].join("\n"),
+                    }],
+            };
+        },
+    },
+    recapture_experiment_screenshots: {
+        description: `${APEX} — Re-run the hosted screenshot capture for a WEB experiment's arms (renders the target URL for control + variant and stores the images shown on the dashboard). Use after the variant is deployed. For unpublished SDK / Cursor drafts, attach localhost shots with attach_experiment_asset instead — hosted recapture of a public URL will be refused.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to re-capture screenshots for."),
+        }),
+        handler: async ({ experimentId }) => {
+            try {
+                const res = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/recapture`, {});
+                const { captured, errors } = res.data;
+                const lines = [
+                    `${APEX} Re-captured ${captured} screenshot${captured === 1 ? "" : "s"} for ${experimentId}.`,
+                ];
+                if (errors.length)
+                    lines.push(`  Arm(s) that failed: ${errors.join("; ")}`);
+                if (captured === 0) {
+                    lines.push(`  No images were produced — confirm the target URL is public and reachable.`);
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    },
+    verify_experiment_wiring: {
+        description: `${APEX} — Verify an experiment is actually wired up before launch: check whether \`experiment_exposure\` events are arriving for BOTH arms. Use this before activate_experiment to avoid launching an experiment that silently collects no data. Returns a per-arm exposure breakdown and an actionable next step.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to verify wiring for"),
+        }),
+        handler: async ({ experimentId }) => {
+            const wiring = (await apiGet(`/api/experiments/${experimentId}/wiring`)).data;
+            const armLines = wiring.perArm.map(formatArmLine);
+            const zeroArms = wiring.perArm.filter((a) => a.exposures === 0);
+            let verdictLine;
+            let nextStep;
+            switch (wiring.verdict) {
+                case "wired":
+                    verdictLine = `WIRED — all ${wiring.totalArms} arm(s) are producing exposures`;
+                    nextStep =
+                        "Safe to activate. Call activate_experiment to launch — both arms are " +
+                            "already receiving traffic and recording exposures.";
+                    break;
+                case "partial": {
+                    const names = zeroArms
+                        .map((a) => `${a.label} (${a.variantKey})`)
+                        .join(", ");
+                    verdictLine = `PARTIAL — ${wiring.armsLive}/${wiring.totalArms} arm(s) live`;
+                    nextStep =
+                        `These arm(s) have ZERO exposures: ${names}. ` +
+                            "Make sure the variant-serving code returns every variant key (not just the " +
+                            "control) and that traffic is reaching each branch, then re-check. Don't " +
+                            "activate until every arm is producing exposures.";
+                    break;
+                }
+                case "no_exposures":
+                default:
+                    verdictLine = "NO EXPOSURES — no exposures recorded for any arm";
+                    nextStep = wiring.sdkMode
+                        ? "No `experiment_exposure` events have reached Apex yet. This experiment is " +
+                            "code-wired (SDK hook), so you can activate it NOW: activate_experiment will " +
+                            "hold it in `pending_deployment` (\"Waiting on deploy\") and it starts " +
+                            "automatically the moment the deployed `useApexVariant(\"" +
+                            wiring.experimentId +
+                            "\")` code records its first exposure. Ship the code, and the test starts itself."
+                        : "No `experiment_exposure` events are arriving. The variant-serving code " +
+                            "(useApexVariant / Apex.getVariant) probably isn't deployed or running yet, " +
+                            "so nothing is being assigned. Deploy the experiment code and confirm it runs " +
+                            "on the target surface, then re-run verify_experiment_wiring.";
+                    break;
+            }
+            const summary = [
+                `${APEX} Experiment Wiring Check`,
+                `${"═".repeat(40)}`,
+                ``,
+                `  Experiment: ${wiring.experimentId}`,
+                `  Surface: ${wiring.surface}`,
+                `  Status: ${wiring.status}`,
+                `  Verdict: ${verdictLine}`,
+                `  Total exposures: ${wiring.totalExposures}`,
+                ``,
+                `  Per-arm exposures:`,
+                ...armLines,
+                ``,
+                `  Next step: ${nextStep}`,
+                ``,
+                `${"═".repeat(40)}`,
+            ].join("\n");
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    {
+                        type: "text",
+                        text: JSON.stringify({ _apex: true, _type: "wiring_check", ...wiring }, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    activate_experiment: {
+        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. Before flipping to running, this verifies BOTH arms are producing \`experiment_exposure\` events (wiring check). Code-wired (SDK-hook) experiments may be activated before their code ships: the server holds them in \`pending_deployment\` ("Waiting on deploy") and starts on the first exposure. Snippet experiments and journey_arm message tests do not need pre-activation exposures — journey traffic starts on the next send once running. Only wired web experiments that genuinely can't self-start are refused unless force is true. Ask the user to confirm before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to activate"),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Override the wiring safety check and activate even if both arms aren't producing exposures yet. Use only when you knowingly accept launching without verified wiring."),
+        }),
+        handler: async ({ experimentId, force }) => {
+            // Best-effort wiring gate: don't launch an experiment that silently
+            // collects no data. If the wiring endpoint itself errors, don't hard-block.
+            let wiring;
+            let wiringError;
+            try {
+                wiring = (await apiGet(`/api/experiments/${experimentId}/wiring`)).data;
+            }
+            catch (err) {
+                wiringError = err instanceof Error ? err.message : String(err);
+            }
+            // Code-wired (SDK-hook) AND snippet-applied experiments skip the hard
+            // refusal. SDK: the server holds them in `pending_deployment` and
+            // auto-starts on first exposure. Snippet: the Apex snippet only applies
+            // the experiment ONCE IT'S RUNNING, so it can't have pre-activation
+            // exposures — blocking on them is a chicken-and-egg. Both are safe to
+            // launch "early"; wiring is verified AFTER via verify_experiment_wiring.
+            if (wiring && shouldRefuseActivationWiring(wiring, force)) {
+                const armLines = wiring.perArm.map(formatArmLine);
+                const zeroArms = wiring.perArm
+                    .filter((a) => a.exposures === 0)
+                    .map((a) => `${a.label} (${a.variantKey})`);
+                const refusal = [
+                    `${APEX} Activation Refused — experiment is not wired up`,
+                    `${"═".repeat(40)}`,
+                    ``,
+                    `  Did NOT launch ${experimentId}.`,
+                    ``,
+                    `  Both arms must be producing \`experiment_exposure\` events before`,
+                    `  launch. Otherwise you'd start an experiment that silently collects`,
+                    `  no data on one or more arms.`,
+                    ``,
+                    `  Verdict: ${wiring.verdict} (${wiring.armsLive}/${wiring.totalArms} arm(s) live)`,
+                    `  Arm(s) with zero exposures: ${zeroArms.length ? zeroArms.join(", ") : "none"}`,
+                    ``,
+                    `  Per-arm exposures:`,
+                    ...armLines,
+                    ``,
+                    `  To fix: wire up and deploy the variant-serving code`,
+                    `  (useApexVariant / Apex.getVariant) so every arm records exposures,`,
+                    `  then re-run activate_experiment. Or, to override this check and`,
+                    `  launch anyway, re-run with force: true.`,
+                    ``,
+                    `${"═".repeat(40)}`,
+                ].join("\n");
+                return {
+                    content: [
+                        { type: "text", text: refusal },
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                _type: "activation_refused",
+                                reason: "not_wired",
+                                ...wiring,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                status: "running",
+                // Deploy-wait override: the server holds an unwired code-wired
+                // experiment in `pending_deployment` unless the caller forces.
+                ...(force === true ? { force: true } : {}),
+            });
+            // Deploy-wait hold — the server accepted the start but is waiting for
+            // the experiment code to go live. Report the held state precisely
+            // (claiming "LIVE" here would repeat the 2026-07-04 confusion).
+            if (exp.status === "pending_deployment") {
+                const held = [
+                    `${APEX} Experiment Waiting on Deploy`,
+                    `${"═".repeat(40)}`,
+                    ``,
+                    `  "${exp.name}" is armed but NOT collecting yet.`,
+                    `  ID: ${exp.id}`,
+                    `  Status: pending_deployment ("Waiting on deploy")`,
+                    ``,
+                    `  Apex hasn't received any \`experiment_exposure\` events from this`,
+                    `  experiment's code, so the start is on hold. Nothing is wrong —`,
+                    `  the experiment starts AUTOMATICALLY the moment the deployed code`,
+                    `  records its first exposure.`,
+                    ``,
+                    `  To go live:`,
+                    `  1. Render the variants through the hook:`,
+                    `       const variant = useApexVariant("${exp.id}");`,
+                    `     On SSR, assign on the document request and pass that arm`,
+                    `     (initialVariant or <ApexProvider assignments>). The hook`,
+                    `     alone is not flicker-free. If you use Next.js:`,
+                    `     npm install @apex-inc/next @apex-inc/react, then`,
+                    `     apexVisitorMiddleware, assignExperiments,`,
+                    `     <ApexProvider assignments>. Creating this experiment`,
+                    `     did not remove flicker.`,
+                    `  2. Deploy that code to the target page.`,
+                    `  3. Done — the first visitor flips it to running. Verify with`,
+                    `     verify_experiment_wiring or the experiment page.`,
+                    ``,
+                    `  Certain the code is already live? Re-run activate_experiment`,
+                    `  with force: true to start immediately.`,
+                    ``,
+                    `${"═".repeat(40)}`,
+                ].join("\n");
+                return {
+                    content: [
+                        { type: "text", text: held },
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                _type: "activation_held",
+                                reason: "code_not_live",
+                                experimentId: exp.id,
+                                status: exp.status,
+                                autoStartsOnFirstExposure: true,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // PATCH returns a minimal/legacy body — re-read the unified record to
+            // derive the live traffic split from the allocation weights.
+            let controlPct = 50;
+            let liveSurface = exp.surface;
+            try {
+                const unified = await apiGet(`/api/experiments/${experimentId}?unified=true`);
+                controlPct = controlPctOf(unified);
+                liveSurface = unified.surface ?? liveSurface;
+            }
+            catch { /* fall back to 50/50 in the message */ }
+            // Surface why the wiring gate didn't block: either it couldn't be
+            // verified (best-effort) or the user explicitly forced past it.
+            const notes = [];
+            if (wiringError) {
+                notes.push(`  ⚠ Wiring could not be verified before launch (${wiringError}).`, `    Confirm both arms are recording exposures via verify_experiment_wiring.`, ``);
+            }
+            else if (wiring && !wiring.bothArmsLive && force === true) {
+                notes.push(`  ⚠ Launched with force: true despite an incomplete wiring check`, `    (verdict: ${wiring.verdict}, ${wiring.armsLive}/${wiring.totalArms} arm(s) live).`, `    Some arm(s) may not be collecting data yet.`, ``);
+            }
+            else if (wiring && !wiring.bothArmsLive && wiring.snippetMode) {
+                notes.push(`  ℹ Snippet experiment — the Apex snippet applies it to visitors now`, `    that it's running, so exposures start flowing on the next visits.`, `    Confirm both arms record exposures shortly with`, `    verify_experiment_wiring (a mismatched selector would silently`, `    collect nothing).`, ``);
+            }
+            // Author-time conflict guard (advisory): if this now-running experiment
+            // overlaps another live one on the same surface, surface the fix.
+            try {
+                const cc = await apiPost("/api/experiments/check-conflicts", { experiment_id: experimentId });
+                if (hasConflictAdvisory(cc.data)) {
+                    notes.push(`  ${renderConflictAdvisory(cc.data, experimentId).split("\n").join("\n  ")}`, ``);
+                }
+            }
+            catch {
+                /* advisory only — never affect the launch result */
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Experiment Launched`,
+                            `${"═".repeat(40)}`,
+                            ``,
+                            `  "${exp.name}" is now LIVE`,
+                            `  ID: ${exp.id}`,
+                            `  Traffic is being split ${controlPct}% / ${100 - controlPct}%`,
+                            ``,
+                            ...notes,
+                            `  ${activationLiveLine(liveSurface)}`,
+                            `  Results will appear in the dashboard and via get_results.`,
+                            ``,
+                            `${"═".repeat(40)}`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    pause_experiment: {
+        description: `${APEX} — Pause a running experiment. All visitors will see the control until resumed. Ask the user to confirm before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to pause"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                status: "paused",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Experiment Paused`,
+                            ``,
+                            `  "${exp.name}" is now paused.`,
+                            `  All visitors will see the control version.`,
+                            `  Data collected so far is preserved.`,
+                            ``,
+                            `  To resume, use activate_experiment.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    track_deployment: {
+        description: `${APEX} — Record that an experiment's code has been committed and pushed. Stores the commit SHA and monitors deployment status. Call after pushing the experiment code.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            commitSha: z.string().describe("The git commit SHA containing the experiment code"),
+            branch: z.string().optional().describe("The git branch (default: main)"),
+        }),
+        handler: async ({ experimentId, commitSha, branch }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                deploymentCommit: commitSha,
+                deploymentStatus: "building",
+            });
+            const recipe = {
+                _apex: true,
+                _type: "deployment_tracked",
+                experimentId: exp.id,
+                commitSha,
+                branch: branch || "main",
+                deploymentStatus: "building",
+                _instructions: [
+                    "The experiment code is now being deployed.",
+                    "Wait for the build to complete, then call check_deployment.",
+                    "Once deployed, call activate_experiment to start collecting data.",
+                    "Ask the user if they want to wait for deployment or activate later.",
+                ].join("\n"),
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    check_deployment: {
+        description: `${APEX} — Check if an experiment's code has been deployed. Verifies that the assignment endpoint responds for this experiment. Call after track_deployment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to check"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiGet(`/api/experiments/${experimentId}?unified=true`);
+            if (!exp) {
+                return { content: [{ type: "text", text: JSON.stringify({ _apex: true, error: "Experiment not found" }) }] };
+            }
+            let isReachable = false;
+            try {
+                const BASE_URL = process.env.APEX_URL || "http://localhost:3001";
+                const res = await fetch(`${BASE_URL}/api/experiments/${experimentId}/assign`, {
+                    signal: AbortSignal.timeout(5000),
+                });
+                isReachable = res.ok;
+            }
+            catch { /* unreachable */ }
+            const status = isReachable ? "deployed" : (exp.deploymentStatus || "pending");
+            if (isReachable && exp.deploymentStatus !== "deployed") {
+                await apiPatch("/api/experiments", {
+                    id: experimentId,
+                    deploymentStatus: "deployed",
+                    deployedAt: new Date().toISOString(),
+                });
+            }
+            const recipe = {
+                _apex: true,
+                _type: "deployment_check",
+                experimentId,
+                deploymentStatus: status,
+                commitSha: exp.deploymentCommit || null,
+                isReachable,
+                _instructions: isReachable
+                    ? "Deployment confirmed. Ask the user if they want to activate the experiment now."
+                    : "Deployment not yet confirmed. The build may still be in progress. Try again in a minute or ask the user to check their CI/CD.",
+            };
+            return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
+        },
+    },
+    archive_experiment: {
+        description: `${APEX} — Archive an experiment. Removes it from active views but preserves all data, learnings, and belief graph connections. Archived experiments still contribute to intelligence scoring and recommendations. A RUNNING experiment cannot be archived — end it first (conclude_experiment / promote_winner) so its result + belief are captured; the server returns 409 archive_requires_conclusion otherwise. Ask the user to confirm before calling.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to archive"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiPatch("/api/experiments", {
+                id: experimentId,
+                status: "archived",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Experiment Archived`,
+                            ``,
+                            `  "${exp.name}" has been archived.`,
+                            `  It no longer appears in active views, but all data is preserved.`,
+                            `  Learnings and belief graph connections remain intact.`,
+                            ``,
+                            `  To view archived experiments: list_experiments with status "archived"`,
+                            `  To restore: activate_experiment to resume, or pause_experiment to keep inactive.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    list_experiments: {
+        description: `${APEX} — List the user's Apex experiments. Call this ONLY when the user explicitly asks about their experiments or what's running/ready to graduate. Do not call it proactively for unrelated tasks. Archived experiments are hidden by default — pass status "archived" to see them, or "all" to see everything. Experiments that are promoted but not graduated are flagged as PENDING GRADUATION.`,
+        schema: z.object({
+            status: z
+                .enum(["all", "running", "completed", "draft", "paused", "archived"])
+                .optional()
+                .describe("Filter by status. Defaults to showing all except archived."),
+        }),
+        handler: async ({ status }) => {
+            const experiments = await apiGet("/api/experiments?unified=true");
+            const filtered = status === "all"
+                ? experiments
+                : status
+                    ? experiments.filter((e) => e.status === status)
+                    : experiments.filter((e) => e.status !== "archived");
+            if (filtered.length === 0) {
+                return { content: [{ type: "text", text: `${APEX} No experiments found.` }] };
+            }
+            const pendingGraduation = filtered.filter((e) => e.promoted && !e.graduated);
+            const lines = filtered.map((e) => {
+                const ctrl = e.results?.perVariant?.control;
+                const varB = e.results?.perVariant?.variant_b;
+                const isPendingGrad = !!(e.promoted && !e.graduated);
+                const statusIcon = isPendingGrad
+                    ? "⬆"
+                    : e.status === "running" ? "●" : e.status === "draft" ? "○" : e.status === "paused" ? "◐" : "◉";
+                const statusLabel = isPendingGrad
+                    ? `${e.status}] [PENDING GRADUATION`
+                    : e.status;
+                const winnerVariant = e.winner ? findVariant(e, e.winner) : undefined;
+                const changeSummary = isPendingGrad && winnerVariant?.changes?.length
+                    ? `  Changes to graduate: ${winnerVariant.changes.map((c) => `"${c.originalValue ?? c.value}" → "${c.value}"`).join(", ")}`
+                    : "";
+                return [
+                    `${statusIcon} ${e.name} [${statusLabel}]`,
+                    `  ID: ${e.id}`,
+                    `  URL: ${e.targetUrl ?? "—"} | ${daysRunningOf(e)}d running`,
+                    ctrl && varB
+                        ? `  Control: ${ctrl.conversionRate ?? 0}% CVR (${ctrl.assigned} visitors) | Variant: ${varB.conversionRate ?? 0}% CVR (${varB.assigned} visitors)`
+                        : "  No results yet",
+                    e.beliefId ? `  Belief: ${e.beliefId}` : "",
+                    changeSummary,
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+            });
+            let header = `${APEX} Experiments (${filtered.length})`;
+            if (pendingGraduation.length > 0) {
+                header += ` — ${pendingGraduation.length} pending graduation`;
+            }
+            return { content: [{ type: "text", text: `${header}\n${"─".repeat(40)}\n\n${lines.join("\n\n")}` }] };
+        },
+    },
+    get_results: {
+        description: `${APEX} — Get the website experiment card: visitors, conversions, and confidence from GET /api/experiments/:id?unified=true. For readiness (collecting / decisive / inconclusive) or a letter Experiment step, use get_experiment_results.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experimentId }) => {
+            const exp = await apiGet(`/api/experiments/${experimentId}?unified=true`);
+            if (!exp) {
+                return { content: [{ type: "text", text: `${APEX} Experiment ${experimentId} not found.` }] };
+            }
+            const ctrl = exp.results?.perVariant?.control;
+            const varB = exp.results?.perVariant?.variant_b;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Results: ${exp.name}`,
+                            `${"═".repeat(40)}`,
+                            ``,
+                            `  Status:     ${exp.status}`,
+                            `  Running:    ${daysRunningOf(exp)} days`,
+                            `  Confidence: ${exp.confidence ?? 0}%`,
+                            `  URL:        ${exp.targetUrl ?? "—"}`,
+                            ``,
+                            `  Control:`,
+                            ctrl
+                                ? `    ${ctrl.assigned} visitors | ${ctrl.converted} conversions | ${ctrl.conversionRate ?? 0}% CVR`
+                                : "    No data yet",
+                            `  Variant B:`,
+                            varB
+                                ? `    ${varB.assigned} visitors | ${varB.converted} conversions | ${varB.conversionRate ?? 0}% CVR`
+                                : "    No data yet",
+                            exp.beliefId ? `\n  Linked belief: ${exp.beliefId}` : "",
+                            ``,
+                            `${"═".repeat(40)}`,
+                            ``,
+                            `Present the user with options:`,
+                            `  1. Keep running — need more data`,
+                            `  2. Promote winner — if the result is clear`,
+                            `  3. Pause — stop collecting temporarily`,
+                            `  4. Suggest next experiment — what to test next`,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    list_beliefs: {
+        description: `${APEX} — List the workspace's beliefs (the assumptions experiments test). Shows confidence, validation state, and AI-generated provenance so you can LINK an existing belief instead of minting a duplicate.`,
+        schema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe("Filter beliefs by a keyword in the statement"),
+        }),
+        handler: async ({ query }) => {
+            const beliefs = await apiGet("/api/beliefs");
+            const q = query?.toLowerCase().trim();
+            const filtered = q
+                ? beliefs.filter((b) => b.statement.toLowerCase().includes(q))
+                : beliefs;
+            if (filtered.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No beliefs${q ? ` matching "${query}"` : ""} yet. You can generate one from a hypothesis when creating an experiment.`,
+                        },
+                    ],
+                };
+            }
+            const lines = filtered
+                .slice(0, 50)
+                .map((b) => {
+                const tags = [
+                    `${Math.round(b.confidence * 100)}% confidence`,
+                    b.validationState === "unvalidated" ? "unvalidated" : null,
+                    b.generatedFromExperimentId ? "AI-generated" : null,
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+                return `  • [${b.id}] ${b.statement} (${tags})`;
+            })
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Beliefs (${filtered.length})`,
+                            `${"═".repeat(40)}`,
+                            lines,
+                            ``,
+                            `Link one to a new experiment with its id, or generate a fresh belief from your hypothesis.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    update_experiment: {
+        description: `${APEX} — Edit an EXISTING experiment. Editability is gated by lifecycle: a DRAFT (with no exposures yet) is fully editable; once it has data or is running, the pre-registration (hypothesis, metric, guardrails) and bucketing (surface, variants) freeze and edits return a clear "experiment_locked" reason. After freeze, fork_experiment instead. Use this to fix a mislabeled surface or correct a draft before launch.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment id to edit."),
+            name: z.string().optional().describe("Rename (cosmetic; editable anytime)."),
+            surface: z.enum(["web", "mobile"]).optional().describe("Correct the surface — editable only on a draft with 0 exposures (web↔mobile)."),
+            hypothesis: z.string().optional().describe("Edit the hypothesis — draft only (pre-registration)."),
+            targetUrl: z.string().optional().describe("Retarget a DRAFT to a URL on the ACTIVE workspace. Same host rules as create_experiment."),
+            predictionId: z.string().optional().describe("Attach a minted prediction id (from log_prediction) to this draft. Also stamps the prediction onto the experiment's hypothesis when that link is missing. Required before activation."),
+            primaryMetricEvent: z.string().optional().describe("Change the primary metric's canonical event — draft only."),
+            primaryMetricType: z.enum(["rate", "count", "revenue", "duration"]).optional(),
+            guardrailEvent: z.string().optional().describe("Replace the guardrail with this canonical protective event — draft only."),
+            minSamplePerArm: z.number().int().min(30).optional().describe("Set the minimum exposed subjects PER ARM before a winner can be claimed (the sample gate; floor 30). Draft only — it's part of the pre-registration and freezes at launch (a running experiment returns experiment_locked; fork to change it)."),
+            runtimeDays: z.number().int().min(1).max(365).optional().describe("Set how long to run the experiment, in days (the decision window Apex force-concludes at). Draft only — part of the pre-registration; freezes at launch (fork to change it)."),
+        }),
+        handler: async (args) => {
+            if (args.targetUrl) {
+                const targetCheck = await assertTargetUrlForActiveWorkspace(args.targetUrl);
+                if (!targetCheck.ok) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} ${targetCheck.message}` }],
+                        isError: true,
+                    };
+                }
+            }
+            const body = { id: args.experimentId };
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.surface !== undefined)
+                body.surface = args.surface;
+            if (args.hypothesis !== undefined)
+                body.hypothesis = args.hypothesis;
+            if (args.targetUrl !== undefined)
+                body.targetUrl = args.targetUrl;
+            if (args.predictionId !== undefined)
+                body.predictionId = args.predictionId;
+            // evaluationWindow patch — the API merges it, so setting one of
+            // minPerVariant / durationDays never clobbers the other.
+            if (args.minSamplePerArm !== undefined || args.runtimeDays !== undefined) {
+                const ew = {};
+                if (args.minSamplePerArm !== undefined)
+                    ew.minPerVariant = args.minSamplePerArm;
+                if (args.runtimeDays !== undefined)
+                    ew.durationDays = args.runtimeDays;
+                body.evaluationWindow = ew;
+            }
+            if (args.primaryMetricEvent) {
+                const t = args.primaryMetricType ?? "rate";
+                const isValue = t === "revenue" || t === "duration";
+                body.primaryMetric = {
+                    key: `${args.primaryMetricEvent}_${t}`,
+                    label: titleCaseEvent(args.primaryMetricEvent),
+                    type: t,
+                    unit: t === "revenue" ? "USD" : t === "duration" ? "s" : "%",
+                    direction: "increase",
+                    source: isValue
+                        ? { kind: "event", eventType: args.primaryMetricEvent, property: "value" }
+                        : { kind: "event", eventType: args.primaryMetricEvent },
+                };
+            }
+            if (args.guardrailEvent) {
+                body.guardrailMetrics = [
+                    {
+                        key: `${args.guardrailEvent}_rate`,
+                        label: `${titleCaseEvent(args.guardrailEvent)} rate`,
+                        type: "rate",
+                        unit: "%",
+                        direction: "decrease",
+                        source: { kind: "event", eventType: args.guardrailEvent },
+                        guardrailThreshold: 0.25,
+                        thresholdKind: "relative",
+                    },
+                ];
+            }
+            try {
+                const updated = await apiPatch("/api/experiments", body);
+                // Tenant echo: never report success for a record outside the active workspace.
+                const active = getActiveWorkspace();
+                if (active && updated.workspaceKey && updated.workspaceKey !== active) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} Refusing to confirm: the updated record belongs to a different workspace.` }],
+                        isError: true,
+                    };
+                }
+                const applied = Object.keys(body).filter((k) => k !== "id");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} Updated "${updated.name}" (${updated.surface}, ${updated.status}). Applied: ${applied.join(", ") || "nothing"}.`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                // Surface the lock reason verbatim (409 experiment_locked etc.).
+                return {
+                    content: [{ type: "text", text: `${APEX} ${err instanceof Error ? err.message : String(err)}` }],
+                    isError: true,
+                };
+            }
+        },
+    },
+    fork_experiment: {
+        description: `${APEX} — Duplicate a frozen experiment's design into a fresh editable DRAFT. Use this after update_experiment reports "experiment_locked" (running or has exposures). The fork carries NO data (no results, assignments, or winner) and records its lineage; edit it freely, then activate.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment id to fork."),
+        }),
+        handler: async ({ experimentId }) => {
+            try {
+                const forked = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/fork`, {});
+                const active = getActiveWorkspace();
+                if (active && forked.workspaceKey && forked.workspaceKey !== active) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} Refusing to confirm: the fork belongs to a different workspace.` }],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `${APEX} Forked into a fresh draft "${forked.name}" (id: ${forked.id}).`,
+                                ``,
+                                `A copy gets a new id. The page still asks the old one until you replace it.`,
+                                `  Find:    const variant = useApexVariant("${experimentId}");`,
+                                `  Replace: const variant = useApexVariant("${forked.id}");`,
+                                `Deploy that change, then activate.`,
+                                `Preview still works via _apex_exp. A normal visit shows control until the new id is shipped.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `${APEX} ${err instanceof Error ? err.message : String(err)}` }],
+                    isError: true,
+                };
+            }
+        },
+    },
+    check_experiment_conflicts: {
+        description: `${APEX} — Before you create or activate an experiment, check who else is live on that page. Pin a part (target_anchor) so two homepage experiments are not the same place. Whole page plus a part is one place. Different named parts: the same person can see both — say so, do not add the two lifts. Overlap: Someone could see both; Keep them apart with set_experiment_mutex, or wait. Shared conversion on the allowed mix: one experiment or wait. Pass either experimentId OR the candidate's location + primaryMetricEvent. Advisory only.`,
+        schema: z.object({
+            experimentId: z.string().optional().describe("Check an existing experiment by id (loads its location + metric)."),
+            surface: z.enum(["web", "mobile"]).optional(),
+            targetComponent: z.string().optional().describe("Component/file the experiment changes, e.g. 'ProductCard'."),
+            targetUrl: z.string().optional(),
+            targetAnchor: z.string().optional(),
+            dataSourceId: z.string().optional(),
+            primaryMetricEvent: z.string().optional().describe("Canonical primary-metric event, e.g. 'add_to_cart'."),
+        }),
+        handler: async (args) => {
+            try {
+                const res = await apiPost("/api/experiments/check-conflicts", {
+                    ...(args.experimentId ? { experiment_id: args.experimentId } : {}),
+                    surface: args.surface,
+                    target_component: args.targetComponent,
+                    target_url: args.targetUrl,
+                    target_anchor: args.targetAnchor,
+                    data_source_id: args.dataSourceId,
+                    primary_metric_event: args.primaryMetricEvent,
+                });
+                return { content: [{ type: "text", text: `${APEX} ${renderConflictAdvisory(res.data, args.experimentId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    check_live_tests: {
+        description: `${APEX} — Before you edit a page, commit, or push, call this even if the user did not mention experiments. Also call it before you change a letter, Adaptive Journey, or Milestone. If something live is on those files or ids, stop and ask. Do not edit. Do not commit.`,
+        schema: z.object({
+            file_paths: z
+                .array(z.string())
+                .optional()
+                .describe("Repo-relative paths you are about to edit or commit. Full file is read locally when content is omitted."),
+            file_contents: z
+                .array(z.object({
+                path: z.string(),
+                content: z.string().describe("Full file at HEAD, not the diff hunk."),
+            }))
+                .optional(),
+            urls: z
+                .array(z.string())
+                .optional()
+                .describe("Page URLs you are about to change. URL-only hits are a warning, not a stop."),
+            communication_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Letters you are about to edit or publish."),
+            journey_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Adaptive Journeys you are about to change or publish."),
+            milestone_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Milestones you are about to change or delete."),
+        }),
+        handler: async (args) => {
+            try {
+                const byPath = new Map();
+                for (const row of args.file_contents ?? []) {
+                    if (row?.path)
+                        byPath.set(row.path, { path: row.path, content: row.content });
+                }
+                for (const raw of args.file_paths ?? []) {
+                    if (!raw || byPath.has(raw))
+                        continue;
+                    const abs = raw.startsWith("/") ? raw : join(process.cwd(), raw);
+                    byPath.set(raw, {
+                        path: raw,
+                        content: existsSync(abs) ? readFileSync(abs, "utf8") : undefined,
+                    });
+                }
+                const files = [...byPath.values()];
+                const hits = await fetchLiveTestHits({
+                    files,
+                    urls: args.urls,
+                    communicationIds: args.communication_ids,
+                    journeyIds: args.journey_ids,
+                    milestoneIds: args.milestone_ids,
+                    includePublishedJourneys: (args.journey_ids ?? []).length > 0,
+                });
+                const stopping = hits.filter((h) => isFileStop(h) || isObjectStop(h));
+                if (stopping.length === 0) {
+                    if (hits.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `${APEX} Nothing live is on those files or ids. You can edit and commit.`,
+                                },
+                            ],
+                        };
+                    }
+                    const soft = hits
+                        .map((h) => `${h.name} (${h.status}, ${h.confidence}: ${h.reason})`)
+                        .join("; ");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${APEX} Soft warning only — not a stop: ${soft}. If you turn a paused test back on, this is the page.`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatLiveTestStop(stopping),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    set_experiment_mutex: {
+        description: `${APEX} — Put two experiments in a mutual-exclusion group: no visitor is ever assigned to both, so they run concurrently with partitioned traffic (the scientifically clean way to run two experiments that touch the same surface). Bidirectional. Pass mode:"remove" to unlink. Safe on running experiments — only affects future assignments.`,
+        schema: z.object({
+            experimentId: z.string(),
+            withExperimentId: z.string().describe("The other experiment to make mutually exclusive with."),
+            mode: z.enum(["add", "remove"]).optional().describe("'add' (default) links; 'remove' unlinks."),
+        }),
+        handler: async ({ experimentId, withExperimentId, mode }) => {
+            try {
+                await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/mutex`, { withExperimentId, mode });
+                const verb = mode === "remove" ? "are no longer" : "are now";
+                return { content: [{ type: "text", text: `${APEX} ${experimentId} and ${withExperimentId} ${verb} mutually exclusive — no visitor will be assigned to both.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    suggest_experiment: {
+        description: `${APEX} — Get smart experiment suggestions based on context. Analyzes your assumptions, past experiments, and confidence gaps to recommend what to test next.`,
+        schema: z.object({
+            context: z
+                .string()
+                .optional()
+                .describe("What you're working on (e.g. 'redesigning onboarding', 'pricing page optimization')"),
+        }),
+        handler: async ({ context }) => {
+            const [beliefs, experiments] = await Promise.all([
+                apiGet("/api/beliefs"),
+                apiGet("/api/experiments?unified=true"),
+            ]);
+            const lowConfidence = beliefs.filter((b) => b.confidence < 0.6 && b.confidence > 0.05);
+            const untested = beliefs.filter((b) => b.confidence > 0.05 && !experiments.some((e) => e.beliefId === b.id));
+            const completed = experiments.filter((e) => e.status === "completed");
+            const running = experiments.filter((e) => e.status === "running");
+            const contextKeywords = context
+                ? context.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((w) => w.length > 3)
+                : [];
+            const relevantBeliefs = contextKeywords.length > 0
+                ? beliefs.filter((b) => {
+                    const words = b.statement.toLowerCase();
+                    return contextKeywords.some((kw) => words.includes(kw));
+                })
+                : [];
+            const relevantExperiments = contextKeywords.length > 0
+                ? completed.filter((e) => {
+                    const words = e.name.toLowerCase();
+                    return contextKeywords.some((kw) => words.includes(kw));
+                })
+                : [];
+            const recs = [];
+            if (context) {
+                recs.push(`**Context**: ${context}`, "");
+            }
+            if (relevantBeliefs.length > 0) {
+                recs.push(`**Related assumptions** (${relevantBeliefs.length}):`, ...relevantBeliefs.slice(0, 5).map((b) => {
+                    const tested = experiments.some((e) => e.beliefId === b.id);
+                    return `  - "${b.statement}" (${Math.round(b.confidence * 100)}% sure) — ${tested ? "tested" : "untested"}`;
+                }), "");
+            }
+            if (relevantExperiments.length > 0) {
+                recs.push(`**Past experiments in this area** (${relevantExperiments.length}):`, ...relevantExperiments.slice(0, 3).map((e) => {
+                    const ctrl = e.results?.perVariant?.control;
+                    const varB = e.results?.perVariant?.variant_b;
+                    const ctrlCvr = ctrl?.conversionRate ?? 0;
+                    const varCvr = varB?.conversionRate ?? 0;
+                    const lift = ctrl && varB && ctrlCvr > 0
+                        ? ((varCvr - ctrlCvr) / ctrlCvr * 100).toFixed(1)
+                        : "N/A";
+                    return `  - "${e.name}" — ${lift}% lift, ${e.confidence}% confidence`;
+                }), "");
+            }
+            if (untested.length > 0) {
+                recs.push(`**Untested assumptions** (${untested.length}):`, ...untested.slice(0, 3).map((b) => `  - "${b.statement}" (${Math.round(b.confidence * 100)}% sure)`), "");
+            }
+            if (lowConfidence.length > 0) {
+                recs.push(`**Low-confidence assumptions that need data**:`, ...lowConfidence.slice(0, 3).map((b) => `  - "${b.statement}" at ${Math.round(b.confidence * 100)}%`), "");
+            }
+            if (completed.length > 0) {
+                recs.push(`**Follow-up opportunities** from ${completed.length} completed experiments:`, ...completed.slice(0, 3).map((e) => `  - "${e.name}" — consider a follow-up variant`), "");
+            }
+            recs.push(`**Current state**: ${beliefs.length} assumptions, ${running.length} running, ${completed.length} completed`);
+            if (recs.length <= 1) {
+                recs.push("", "No specific recommendations yet. Start by tracking an assumption using start_reasoning.");
+            }
+            return { content: [{ type: "text", text: recs.join("\n") }] };
+        },
+    },
+    promote_winner: {
+        description: `${APEX} — Promote the winner on a website experiment card (PATCH /api/experiments action=promote). The snippet serves that arm immediately. For a letter Experiment step, use promote_experiment_winner. After promoting, use graduate_experiment to put the winner in source.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            winner: z.enum(["control", "variant_b"]).describe("Which variant won"),
+        }),
+        handler: async ({ experimentId, winner }) => {
+            const existing = await apiGet(`/api/experiments/${experimentId}?unified=true`);
+            if (existing.status !== "completed" || !existing.winner) {
+                await apiPatch(`/api/experiments`, {
+                    id: experimentId,
+                    status: "completed",
+                    winner,
+                });
+            }
+            const promoted = await apiPatch(`/api/experiments`, {
+                id: experimentId,
+                action: "promote",
+            });
+            // PATCH responses are minimal — winner content / belief link / mode come
+            // from the unified record fetched at the top.
+            const beliefId = existing.beliefId;
+            let beliefUpdate = "";
+            if (beliefId) {
+                try {
+                    const result = await apiPost(`/api/beliefs/${beliefId}/update-confidence`, {
+                        experimentId,
+                        outcome: winner === "variant_b" ? "confirmed" : "contradicted",
+                        metricDelta: winner === "variant_b" ? 0.15 : -0.1,
+                    });
+                    beliefUpdate = `Assumption "${result.belief.statement}" updated to ${Math.round(result.belief.confidence * 100)}% certainty.`;
+                }
+                catch {
+                    beliefUpdate = "Could not update assumption certainty automatically.";
+                }
+            }
+            const winnerVariant = findVariant(existing, winner);
+            const changeSummary = winnerVariant?.changes?.length
+                ? winnerVariant.changes.map((c) => `  • ${c.type}: "${c.originalValue ?? "(unknown)"}" → "${c.value}" (${c.selector})`).join("\n")
+                : "  No DOM changes recorded.";
+            const nextStep = winnerVariant?.mode === "sdk"
+                ? `Use graduate_experiment("${experimentId}") to get cleanup instructions for removing useApexVariant() conditionals from your code.`
+                : `Use graduate_experiment("${experimentId}") to get instructions for making these changes permanent in your source code. The Apex snippet handles serving the winner in the meantime.`;
+            const output = [
+                `${APEX} Winner promoted!`,
+                ``,
+                `Experiment: ${promoted.name}`,
+                `Winner: ${winner}`,
+                `Status: All visitors now see the winning variant via the Apex snippet.`,
+                ``,
+                `Winning changes:`,
+                changeSummary,
+                ``,
+                beliefUpdate ? `${beliefUpdate}\n` : "",
+                `Next step: ${nextStep}`,
+            ].filter(Boolean).join("\n");
+            return { content: [{ type: "text", text: output }] };
+        },
+    },
+    get_experiment_results: {
+        description: `${APEX} — Readiness + results for a letter Experiment step (or any experiment): collecting / decisive / inconclusive / guardrail from GET /api/experiments/:id/results. For the website experiment card (visitors and conversions), use get_results.`,
+        schema: z.object({
+            experiment_id: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experiment_id }) => {
+            const body = await apiGet(`/api/experiments/${experiment_id}/results`);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(body, null, 2) },
+                ],
+            };
+        },
+    },
+    promote_experiment_winner: {
+        description: `${APEX} — Promote the winner of a letter Experiment step (or any unified experiment). Re-verifies the readiness gate server-side and writes the winning variant's content into the canonical communication as a new version; losing variants are archived. For the website experiment card, use promote_winner. Pass force=true to override "not enough people yet." Force cannot override a page that changed mid-flight.`,
+        schema: z.object({
+            experiment_id: z.string().describe("The experiment ID"),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Override the readiness gate and promote anyway"),
+            winner_key: z
+                .string()
+                .optional()
+                .describe("Explicit winner variant key (defaults to the decisive winner)"),
+        }),
+        handler: async ({ experiment_id, force, winner_key, }) => {
+            const body = await apiPost(`/api/experiments/${experiment_id}/promote`, { force: force ?? false, ...(winner_key ? { winnerKey: winner_key } : {}) });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(body, null, 2) },
+                ],
+            };
+        },
+    },
+    graduate_experiment: {
+        description: `${APEX} — Get instructions to make a promoted experiment's winning changes permanent in the codebase. Returns the original values (for searching in source files) and new values (for replacement). After making the edits and deploying, the Apex snippet automatically detects the native changes and marks the experiment as graduated.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to graduate"),
+        }),
+        handler: async ({ experimentId }) => {
+            const recipe = await apiGet(`/api/experiments/${experimentId}/graduation-recipe`);
+            if (recipe.mode === "sdk") {
+                const output = [
+                    `${APEX} Graduation Recipe — SDK Mode`,
+                    ``,
+                    `Experiment: ${recipe.experimentName}`,
+                    `Winner: ${recipe.winner}`,
+                    ``,
+                    `Steps:`,
+                    `1. Search the codebase for useApexVariant("${recipe.experimentId}")`,
+                    recipe.winner === "variant_b"
+                        ? `2. Replace each variant conditional with ONLY the variant_b branch (remove control)`
+                        : `2. Replace each variant conditional with ONLY the control branch (remove variant_b)`,
+                    `3. Remove the useApexVariant import if no other experiments use it`,
+                    `4. Commit: "Graduate experiment: ${recipe.experimentName} — ${recipe.winner} wins"`,
+                    `5. Deploy. The Apex snippet will detect the native changes and mark the experiment as graduated.`,
+                ].join("\n");
+                return { content: [{ type: "text", text: output }] };
+            }
+            const steps = recipe.changes.map((change, i) => {
+                const lines = [
+                    `Change ${i + 1}: ${change.type} on ${change.selector}`,
+                ];
+                if (change.originalValue) {
+                    lines.push(`  Search for: "${change.originalValue}"`);
+                    lines.push(`  Replace with: "${change.value}"`);
+                }
+                else {
+                    lines.push(`  Apply: "${change.value}" to elements matching ${change.selector}`);
+                }
+                return lines.join("\n");
+            });
+            const output = [
+                `${APEX} Graduation Recipe — Snippet Mode`,
+                ``,
+                `Experiment: ${recipe.experimentName}`,
+                `Winner: ${recipe.winner}`,
+                `Target URL: ${recipe.targetUrl}`,
+                ``,
+                `For each change below, search the codebase for the "Search for" text,`,
+                `find the source file that renders it, and replace with the new value.`,
+                ``,
+                ...steps,
+                ``,
+                `After making all changes:`,
+                `• Commit: "Graduate experiment: ${recipe.experimentName} — ${recipe.winner} wins"`,
+                `• Deploy the changes.`,
+                `• The Apex snippet will detect that the page now natively shows the winning`,
+                `  content and automatically mark the experiment as graduated.`,
+            ].join("\n");
+            return { content: [{ type: "text", text: output }] };
+        },
+    },
+    record_outcome: {
+        description: `${APEX} — Log the outcome of an experiment and update belief confidence. Present the outcome interpretation to the user and let them confirm before recording.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            beliefId: z.string().describe("The assumption ID to update"),
+            outcome: z.enum(["confirmed", "contradicted", "inconclusive"]).describe("Whether the expected outcome happened"),
+            metricDelta: z.number().describe("The observed metric change (e.g. 0.15 for +15%)"),
+            notes: z.string().optional().describe("Optional notes about the outcome"),
+        }),
+        handler: async (args) => {
+            const result = await apiPost(`/api/beliefs/${args.beliefId}/update-confidence`, {
+                experimentId: args.experimentId,
+                outcome: args.outcome,
+                metricDelta: args.metricDelta,
+                notes: args.notes,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Outcome recorded for experiment ${args.experimentId}:`,
+                            `  Result: ${args.outcome} (metric delta: ${args.metricDelta > 0 ? "+" : ""}${(args.metricDelta * 100).toFixed(1)}%)`,
+                            `  Assumption "${result.belief.statement}" updated: ${Math.round(result.belief.confidence * 100)}%`,
+                            `  Learning logged: ${result.ledgerEntry.decision}`,
+                            args.notes ? `  Notes: ${args.notes}` : "",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    predict_impact: {
+        description: `${APEX} — Decision guardrail: predict the impact of a proposed change by searching history for similar experiments. Returns historical data, confidence, and a recommendation.`,
+        schema: z.object({
+            description: z
+                .string()
+                .describe("Description of the proposed change (e.g. 'increase signup form fields from 3 to 5')"),
+        }),
+        handler: async ({ description }) => {
+            const result = await apiPost("/api/predictions/impact", { description });
+            const lines = [
+                `**Impact Prediction**: ${description}`,
+                "",
+                result.summary,
+                "",
+            ];
+            if (result.relatedExperiments.length > 0) {
+                lines.push("**Related experiments:**");
+                for (const exp of result.relatedExperiments) {
+                    const lift = exp.conversionLift !== null ? `${exp.conversionLift > 0 ? "+" : ""}${exp.conversionLift}%` : "N/A";
+                    lines.push(`  - ${exp.experimentName}: ${lift} lift (${exp.visitors} visitors, ${exp.confidence}% confidence)`);
+                }
+                lines.push("");
+            }
+            if (result.relatedBeliefs.length > 0) {
+                lines.push("**Related assumptions:**");
+                for (const b of result.relatedBeliefs) {
+                    lines.push(`  - "${b.statement}" (${Math.round(b.confidence * 100)}% sure)`);
+                }
+                lines.push("");
+            }
+            lines.push(`**Recommendation**: ${result.recommendation.toUpperCase()}`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    evaluate_feature: {
+        description: `${APEX} — Pre-build decision intelligence: evaluate a feature idea against the belief graph, past experiments, and intelligence score before committing to building it.`,
+        schema: z.object({
+            feature: z.string().describe("Description of the feature you're considering building"),
+            targetMetric: z
+                .string()
+                .optional()
+                .describe("The metric you expect this feature to improve (e.g. 'conversion_rate', 'activation')"),
+        }),
+        handler: async ({ feature, targetMetric }) => {
+            const [beliefs, experiments] = await Promise.all([
+                apiGet("/api/beliefs"),
+                apiGet("/api/experiments?unified=true"),
+            ]);
+            const keywords = feature
+                .toLowerCase()
+                .replace(/[^a-z0-9\s]/g, "")
+                .split(/\s+/)
+                .filter((w) => w.length > 3);
+            const relevantBeliefs = beliefs.filter((b) => {
+                const words = b.statement.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const completed = experiments.filter((e) => e.status === "completed");
+            const relevantExperiments = completed.filter((e) => {
+                const words = e.name.toLowerCase();
+                return keywords.some((kw) => words.includes(kw));
+            });
+            const testedBeliefIds = new Set(experiments.map((e) => e.beliefId).filter(Boolean));
+            const untestedRelevant = relevantBeliefs.filter((b) => !testedBeliefIds.has(b.id));
+            const lowConfRelevant = relevantBeliefs.filter((b) => b.confidence < 0.6);
+            const avgLift = relevantExperiments.length > 0
+                ? relevantExperiments.reduce((sum, e) => {
+                    const ctrl = e.results?.perVariant?.control;
+                    const varB = e.results?.perVariant?.variant_b;
+                    const ctrlCvr = ctrl?.conversionRate ?? 0;
+                    const varCvr = varB?.conversionRate ?? 0;
+                    if (ctrl && varB && ctrlCvr > 0) {
+                        return sum + ((varCvr - ctrlCvr) / ctrlCvr) * 100;
+                    }
+                    return sum;
+                }, 0) / relevantExperiments.length
+                : null;
+            const lines = [
+                `**Feature Evaluation**: ${feature}`,
+                targetMetric ? `**Target metric**: ${targetMetric}` : "",
+                "",
+            ].filter(Boolean);
+            if (relevantBeliefs.length > 0) {
+                lines.push(`**What the belief graph says** (${relevantBeliefs.length} related assumptions):`, ...relevantBeliefs.slice(0, 5).map((b) => {
+                    const tested = testedBeliefIds.has(b.id) ? "tested" : "untested";
+                    return `  - "${b.statement}" — ${Math.round(b.confidence * 100)}% sure (${tested})`;
+                }), "");
+            }
+            else {
+                lines.push("**Belief graph**: No existing assumptions about this area. This is a blind spot.", "");
+            }
+            if (relevantExperiments.length > 0) {
+                lines.push(`**Historical evidence** (${relevantExperiments.length} related experiments):`, ...relevantExperiments.slice(0, 5).map((e) => {
+                    const ctrl = e.results?.perVariant?.control;
+                    const varB = e.results?.perVariant?.variant_b;
+                    const ctrlCvr = ctrl?.conversionRate ?? 0;
+                    const varCvr = varB?.conversionRate ?? 0;
+                    const lift = ctrl && varB && ctrlCvr > 0
+                        ? `${((varCvr - ctrlCvr) / ctrlCvr * 100).toFixed(1)}%`
+                        : "N/A";
+                    return `  - "${e.name}": ${lift} lift`;
+                }), avgLift !== null ? `  Average lift in this area: ${avgLift > 0 ? "+" : ""}${avgLift.toFixed(1)}%` : "", "");
+            }
+            else {
+                lines.push("**Historical evidence**: No experiments in this area yet.", "");
+            }
+            if (untestedRelevant.length > 0 || lowConfRelevant.length > 0) {
+                lines.push("**Confidence gaps**:");
+                if (untestedRelevant.length > 0) {
+                    lines.push(`  - ${untestedRelevant.length} untested assumption(s) in this area`);
+                }
+                if (lowConfRelevant.length > 0) {
+                    lines.push(`  - ${lowConfRelevant.length} low-confidence assumption(s) that need more data`);
+                }
+                lines.push("");
+            }
+            const hasEvidence = relevantExperiments.length > 0;
+            const hasAssumptions = relevantBeliefs.length > 0;
+            if (hasEvidence && avgLift !== null && avgLift > 5) {
+                lines.push("**Suggestion**: Historical data supports this direction. Consider building with a measurable experiment wrapped around it.");
+            }
+            else if (hasEvidence && avgLift !== null && avgLift < -5) {
+                lines.push("**Suggestion**: Historical data suggests caution — similar changes had negative impact. Run a focused experiment first.");
+            }
+            else if (hasAssumptions && !hasEvidence) {
+                lines.push("**Suggestion**: You have assumptions but no test data. Run an experiment before committing to a full build.");
+            }
+            else if (!hasAssumptions && !hasEvidence) {
+                lines.push("**Suggestion**: This is uncharted territory. Record your assumptions with create_belief and design an experiment first.");
+            }
+            else {
+                lines.push("**Suggestion**: Mixed signals. Run a targeted experiment to build confidence before a full build.");
+            }
+            return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
+        },
+    },
+    link_experiment: {
+        description: `${APEX} — Link an experiment to a GitHub pull request or issue. The link is what auto-starts the experiment when the PR merges. The convention "apex/exp_XXX" in your PR title also auto-links, but call this explicitly to be sure.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to link"),
+            system: z
+                .enum(["github", "github-issues", "linear", "jira", "trello"])
+                .describe("Which dev tool the work item lives in (github for PRs)"),
+            kind: z.enum(["pr", "issue"]).describe("Pull request or issue/ticket"),
+            repo: z
+                .string()
+                .optional()
+                .describe('"owner/repo" slug for GitHub links'),
+            externalId: z
+                .string()
+                .describe("PR number or issue number (e.g. 482)"),
+            url: z.string().url().optional().describe("Canonical URL of the work item"),
+        }),
+        handler: async (args) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(args.experimentId)}/links`, {
+                system: args.system,
+                kind: args.kind,
+                repo: args.repo,
+                externalId: args.externalId,
+                url: args.url,
+            });
+            const text = res.data
+                ? `Linked experiment ${args.experimentId} to ${args.system} ${args.kind} ${args.repo ?? ""}#${args.externalId}.\n${res.data.url}`
+                : `Could not link: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    unlink_experiment: {
+        description: `${APEX} — Remove an Engineering Link from an experiment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            linkId: z
+                .string()
+                .describe('The link id, or "{system}#{externalId}" (e.g. github#482)'),
+        }),
+        handler: async ({ experimentId, linkId }) => {
+            await apiDelete(`/api/experiments/${encodeURIComponent(experimentId)}/links/${encodeURIComponent(linkId)}`);
+            return {
+                content: [
+                    { type: "text", text: `Unlinked ${linkId} from experiment ${experimentId}.` },
+                ],
+            };
+        },
+    },
+    // ─── Apex Developer CLI (Wave 6.5) — IDE debugging helpers ───────────,
+    gate_experiment_on_merge: {
+        description: `${APEX} — Arm a merge gate: bind an experiment to a linked PR so merging it auto-starts the test. Requires a frozen design spec (primary metric, minimum sample size, max duration, stopping rule) — this is the rigor gate that stops PR latency from changing the rules of the test. Link the PR first with link_experiment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            engineeringLinkId: z.string().describe("The link id of the PR (from list_engineering_links)"),
+            rampOnMerge: z.number().min(0).max(100).optional().describe("Variant traffic split applied on merge (default 50)"),
+            primaryMetric: z.string().describe("Primary metric key (must be one of the experiment's metrics)"),
+            minSampleSize: z.number().int().positive().describe("Minimum per-variant sample size (must exceed the default 10)"),
+            maxDurationDays: z.number().int().positive().describe("Max run duration in days (auto-stop)"),
+            stoppingRule: z.string().describe('Stopping rule, e.g. "bayesian-95" or "fixed-horizon"'),
+        }),
+        handler: async (args) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(args.experimentId)}/gate`, {
+                engineeringLinkId: args.engineeringLinkId,
+                rampOnMerge: args.rampOnMerge ?? 50,
+                designSpec: {
+                    primaryMetric: args.primaryMetric,
+                    minSampleSize: args.minSampleSize,
+                    maxDurationDays: args.maxDurationDays,
+                    stoppingRule: args.stoppingRule,
+                },
+            });
+            const text = res.data
+                ? `Merge gate armed for ${args.experimentId}. Status: ${res.data.status} (waiting on the PR to merge).`
+                : `Could not arm gate: ${res.error ?? "unknown error"}${res.code ? ` (${res.code})` : ""}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    open_graduation_pr: {
+        description: `${APEX} — Open an Apex-authored Graduation PR that inlines the winning variant in the merchant's repo. Requires the repo to be opted in for Apex writes (Automation Controls). The experiment must be promoted with a winner. No LLM — a deterministic, reviewable manifest + branded PR.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID (must be promoted with a winner)"),
+        }),
+        handler: async ({ experimentId }) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/promote`, { openGraduationPr: true });
+            const url = res.data?.graduationPrUrl;
+            const text = url
+                ? `Graduation PR opened: ${url}`
+                : `Could not open graduation PR: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    open_revert_pr: {
+        description: `${APEX} — Open a native-format Revert PR removing a losing experiment's variant. Requires the repo to be opted in for Apex writes.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experimentId }) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/open-revert-pr`, {});
+            const url = res.data?.prUrl;
+            const text = url
+                ? `Revert PR opened: ${url}`
+                : `Could not open revert PR: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    get_automation_controls: {
+        description: `${APEX} — Read the workspace's Graduation Pipeline Automation Controls (on-conclusion behavior, per-repo write allowlist, GitHub visibility, commit/branch conventions).`,
+        schema: z.object({}),
+        handler: async () => {
+            const res = await apiGet(`/api/graduation-pipeline/automation`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(res.data ?? res, null, 2) }],
+            };
+        },
+    },
+    update_automation_controls: {
+        description: `${APEX} — Update the workspace's Graduation Pipeline Automation Controls. Only the fields you pass change. To let Apex open PRs to a repo, add it via writeRepos (or use the dedicated repos endpoint).`,
+        schema: z.object({
+            onWin: z.enum(["do_nothing", "notify", "auto"]).optional(),
+            onLose: z.enum(["do_nothing", "notify", "auto"]).optional(),
+            writeRepos: z.array(z.string()).optional(),
+            githubVisibility: z.enum(["full", "minimal", "off"]).optional(),
+            commitConvention: z.enum(["conventional", "none", "custom"]).optional(),
+            branchConvention: z.enum(["apex", "feature", "feat", "chore", "custom"]).optional(),
+            workingHours: z.enum(["anytime", "off_hours", "business_hours"]).optional(),
+        }),
+        handler: async (args) => {
+            const res = await apiPatch(`/api/graduation-pipeline/automation`, args);
+            return {
+                content: [{ type: "text", text: `Automation Controls updated.\n${JSON.stringify(res.data ?? res, null, 2)}` }],
+            };
+        },
+    },
+    list_engineering_links: {
+        description: `${APEX} — List the PRs and issues linked to an experiment, with their current state.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experimentId }) => {
+            const res = await apiGet(`/api/experiments/${encodeURIComponent(experimentId)}/links`);
+            const links = res.data ?? [];
+            if (links.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No engineering links for experiment ${experimentId}.` }],
+                };
+            }
+            // Surface the link id — it is the required `engineering_link_id` input to
+            // gate_experiment_on_merge. Without it the merge gate can't be armed
+            // through MCP alone (staging dogfood gap 2026-07-16).
+            const lines = links.map((l) => `- ${l.system} ${l.kind} ${l.repo ?? ""}#${l.externalId}${l.state ? ` (${l.state})` : ""}${l.title ? ` — ${l.title}` : ""}\n  ${l.url}\n  link id: ${l.id}`);
+            return {
+                content: [
+                    { type: "text", text: `# Engineering links — ${experimentId}\n\n${lines.join("\n")}` },
+                ],
+            };
+        },
+    },
+    // ─── Conversions & Targets (Goals & Conversions Convergence — PR8) ──────────
+    // A Conversion is the merchant-facing definition of a valued action (the
+    // owned-event matcher managed on /dashboard/conversions). A Target is an
+    // aggregate KPI number to hit by a date. "Goal" is retired as a noun.,
+};
+//# sourceMappingURL=experiments.js.map