@apex-inc/mcp-server 0.9.10 → 0.9.12

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.10",
+  "version": "0.9.12",
   "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,23 @@ 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 — classify by the PROPERTY, not the SDK
+
+`create_experiment` takes a `surface` argument that sets the dashboard's data-source label (**Website** vs **Mobile app**). Choose it by **which property the experiment runs in**, not by which SDK resolves it:
+
+- If the repo is a **mobile app** (has `capacitor.config.*` or `@apex-inc/capacitor-plugin`, or is React-Native/native), use `surface: "mobile"` for **all** its experiments — *even ones you implement with `useApexVariant` in the app's web layer*. They belong to the app, not a website. A mobile app should never show experiments under "Website".
+- Use `surface: "web"` only for an actual website / web app with its own hostname.
+
+(Web variants resolve with `useApexVariant` from `@apex-inc/react`; mobile variants resolve with `Apex.getVariant()` from `@apex-inc/capacitor-plugin` — but the *resolver* doesn't decide the source, the *property* does.)
+
+## 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