@apex-inc/mcp-server 0.9.9 → 0.9.11

package/guardrails/lexicon.md

@@ -0,0 +1,16 @@
+# Lexicon — word-level rules
+
+> Word choices the agent should prefer, avoid, or qualify. Replace every `TODO`.
+
+## Preferred words
+<!-- Vocabulary that sounds like you. -->
+- TODO
+
+## Banned words
+<!-- e.g. "guaranteed", "best", "#1", "cheap", unqualified "free". -->
+- TODO
+
+## Words that require a qualifier
+<!-- e.g. "free shipping" → must state the condition from brand-truth.md.
+     Any discount → must cite the real offer from brand-truth.md. -->
+- TODO

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/mcp-server",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "MCP server for Apex — currently in private beta.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -20,7 +21,8 @@
   ],
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "guardrails"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -35,6 +37,7 @@
   },
   "devDependencies": {
     "@types/node": "^20",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^3.2.0"
   }
 }

package/skills/apex-experimentation/SKILL.md

@@ -7,6 +7,10 @@ description: Design, instrument, and analyze A/B experiments with Apex — SDK a
 
 Apex treats experiments as part of a scientific loop: **beliefs → hypotheses → predictions → experiments → outcomes → updated beliefs**. Your job is to suggest experiments when product or code changes could be validated with data, and to wire instrumentation correctly.
 
+## Grounded experiments — never invent claims
+
+Before writing ANY experiment variant copy, read the merchant's guardrail files if present: `.apex/brand-truth.md` (the facts you may claim), `.apex/brand-voice.md` (tone), `.apex/lexicon.md` (word rules). **Every factual claim in variant copy MUST trace to a line in `.apex/brand-truth.md` — cite which line.** If a claim isn't backed there, ASK the user; do not invent it. (Real incident, 2026-06-15: an agent wrote "Free shipping on every order" for an app that charges $8 under $100 — an ungrounded claim that would have invalidated the test.) If the files are missing, scaffold them via **Apex → Set up Apex → Intelligence → "Set up experiment guardrails"** and ask the owner to fill in the facts first.
+
 ## When to suggest an experiment
 
 Proactively offer Apex when you see:
@@ -27,6 +31,18 @@ Proactively offer Apex when you see:
 
 Prefer **SDK mode** when the user is in an app codebase. Prefer **snippet mode** only when they explicitly use the marketing snippet and cannot deploy code.
 
+## Web vs mobile surface
+
+`create_experiment` takes a `surface` argument: `web` (default) for websites and web apps, `mobile` for native / Capacitor apps. Pass `mobile` for a Capacitor / React-Native / native app so the dashboard labels it **iOS App** instead of **Website**. Web variants resolve with `useApexVariant` (`@apex-inc/react`); mobile variants resolve with `Apex.getVariant()` (`@apex-inc/capacitor-plugin`).
+
+## Visual / style variants — don't ship two identical arms
+
+When the variable under test is **visual** (color, size, spacing, layout) rather than copy:
+
+- **Always visually diff the arms.** A style variant that renders identical to control measures nothing. Screenshot both arms and look before activating — the screenshot pipeline exists partly to catch this. (Real incident, 2026-06-15: both arms shipped green because a class override silently lost.)
+- **Class overrides are a trap without tailwind-merge.** Plain `className` concatenation keeps BOTH classes (e.g. `bg-primary` + `bg-black`) and the original usually wins, so the "variant" renders like control. Use an inline `style={{...}}` override or a class with guaranteed precedence.
+- **One variable per test.** Change only the thing under test; keep everything else identical to control.
+
 ## Connecting from your IDE (no API key needed)
 
 Apex MCP uses an **OAuth device flow** — you don't paste an API key. On the
@@ -47,6 +63,7 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 ## Screenshots, exposure & the wiring gate
 
 - **Screenshots are first-class.** For public web URLs, `create_experiment` auto-captures control + variant screenshots and shows them on the dashboard experiment card + detail gallery. For localhost / auth-gated / mobile screens, capture the image yourself and call `attach_experiment_asset({ experimentId, variantKey, imageBase64 })`.
+- **Mobile/Capacitor experiments capture on-device.** When the experiment runs on an authed in-app screen (servers can't reach it), tell the dev to call `Apex.captureVariantScreenshot({ experimentId, variantKey })` on the variant's screen, keyed to the resolved variant in a `useEffect`, in a debug build (`Apex.initialize({ ..., debug: true })`). It no-ops in production and lands the shot on the dashboard card + gallery like web/agent captures.
 - **Exposure auto-fires.** When a variant resolves via `useApexVariant` (web) or `Apex.getVariant()` (mobile), the SDK fires the canonical `experiment_exposure` event — the denominator for results. You don't fire it manually.
 - **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`: both arms must be producing `experiment_exposure` events first, or it refuses (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after deploying the variant code to confirm both arms are live before launch.