@apex-inc/mcp-server 0.40.0 → 0.41.1

package/skills/apex-integration-cookbook/SKILL.md

@@ -337,15 +337,11 @@ financial boundary with no API-key lane).
 
 ## Recipe: Set up Apex from this repo
 
+The full flow lives in the `apex-setup` skill and the `/setup-apex` prompt: sign in, which workspace this repo is, name it, install, watch events arrive, conversion, checklist, browser steps, first value.
+
 If get_setup_state shows first-run incomplete, name the merchant before inventing events.
 
-1. Call `get_setup_state`. If the shop has no name, no vertical, or no conversion model, stop.
-2. `update_organization` with the shop's real name. `update_workspace` with `workspace_name`, `vertical`, `conversion_model`, and `website_url` when you know them. The rail finishes from those saves — do not look for a mark-complete tool.
-3. Name Production (and optional Beta) sites with `list_workspace_environments` / `set_workspace_environments` before you trust the Production slice.
-4. Install the snippet or SDK and wire the events the shop actually fires. Do not invent event names to make a step look done.
-5. Finish writable setup with the matching tools (`claim_links_subdomain`, `set_consent_posture`, webhooks, scoring, invitations, engagement, app platforms, attribution, sender domain, push keys, protect auto-pause). Consent answers are not a live-site tap. Sender-domain records issued are not green — poll `get_sender_domain` until verified.
-6. Hop only when the next incomplete step is a hop: `start_integration_install` for GitHub, Stripe, Meta, Google, LinkedIn, or TikTok. Legal acknowledgements stay on the opened page. You cannot click the ad consoles or the DNS registrar for them.
-7. After ads are connected, make a paid Apex Link before inventing UTMs. Do not stamp conversion ack. `create_apex_link` writes the paid medium. `set_ad_measurement_events` chooses which sales to forward and returns a URL if the legal sentence is still open. `set_conversion_source_of_truth` picks who owns the sale. The rail finishes when those things exist — there is no mark-complete tool.
+After ads are connected, make a paid Apex Link before inventing UTMs. Do not stamp conversion ack. `create_apex_link` writes the paid medium. `set_ad_measurement_events` chooses which sales to forward and returns a URL if the legal sentence is still open. `set_conversion_source_of_truth` picks who owns the sale. The rail finishes when those things exist — there is no mark-complete tool.
 
 ## Recipe: Apex Links for app installs (Mobile Measurement)
 
@@ -358,7 +354,7 @@ const apex = createManagementClient({ apiKey, workspaceKey, apiUrl });
 // One link per campaign. UTMs become the campaign on the Mobile home's table.
 const link = await apex.links.create({
   slug: "spring-bows",
-  destinationUrl: "https://shop.example.com/spring",
+  destinationUrl: "https://www.example.com/spring",
   utmSource: "meta",
   utmMedium: "paid_social",
   utmCampaign: "spring-bows",
@@ -372,18 +368,18 @@ Experiments live under `apex.experiments.*` (`list`, `get`, `getResults`, `activ
 
 ## Recipe: Buyer lists on ad platforms (MCP)
 
-A buyer list is one of the shop's segments, kept on Meta, Google or LinkedIn by Apex and refreshed every day. The shop picks it on an ad set once, to leave buyers out of prospecting or to find more people like them. Same as Attribution → Ad platforms → Who sees your ads.
+A buyer list is one of the workspace's segments, kept on Meta, Google or LinkedIn by Apex and refreshed every day. The owner picks it on an ad set once, to leave buyers out of prospecting or to find more people like them. Same as Attribution → Ad platforms → Who sees your ads.
 
 1. `list_audiences` shows each list, its segment, the goal it was made for, the platforms it goes to, the platforms it actually reached, and how many people it holds back.
-2. `update_audience` changes where a list goes (`platforms`) or how many people are held back (`holdout_percent`: 0, 5, 10 or 20). 0 stops holding anyone back. Dropping a platform the list already reached deletes the list there, which cannot be undone. Without `confirm_delete: true` the tool changes nothing and lists those platforms in `would_delete_from`; ask the shop, then call again with it. A platform that refuses the delete comes back in `refused`.
-3. `remove_audience` takes the list off every platform it reached. It cannot be undone and any ad set using it stops using it, so ask the shop first and pass `confirm: true` only after they say yes. A platform that refuses comes back in `refused`; tell the shop to delete it there by hand.
+2. `update_audience` changes where a list goes (`platforms`) or how many people are held back (`holdout_percent`: 0, 5, 10 or 20). 0 stops holding anyone back. Dropping a platform the list already reached deletes the list there, which cannot be undone. Without `confirm_delete: true` the tool changes nothing and lists those platforms in `would_delete_from`; ask the owner, then call again with it. A platform that refuses the delete comes back in `refused`.
+3. `remove_audience` takes the list off every platform it reached. It cannot be undone and any ad set using it stops using it, so ask the owner first and pass `confirm: true` only after they say yes. A platform that refuses comes back in `refused`; tell the owner to delete it there by hand.
 
 A held-back list that belongs to an Ad holdout experiment is the experiment's. These tools refuse it; pause or archive the experiment instead.
 
-When someone asks to be deleted or opts out of ads, Apex takes them off every list right away. If a platform refuses or isn't connected, they stay on it, and `list_audience_removals` shows them: how many each list still owes per platform, why, and what the platform said. Apex retries every day for 30 days, then stops (`stopped_retrying`) and waits for the shop. Tell the shop plainly that people who asked to be removed are still being shown ads there. If `why` is `not_connected`, the shop reconnects the platform; then call `retry_audience_removals` with the list's id, which also tries the ones Apex stopped on. Its `still_owed` says who is left.
+When someone asks to be deleted or opts out of ads, Apex takes them off every list right away. If a platform refuses or isn't connected, they stay on it, and `list_audience_removals` shows them: how many each list still owes per platform, why, and what the platform said. Apex retries every day for 30 days, then stops (`stopped_retrying`) and waits for the owner. Tell the owner plainly that people who asked to be removed are still being shown ads there. If `why` is `not_connected`, the owner reconnects the platform; then call `retry_audience_removals` with the list's id, which also tries the ones Apex stopped on. Its `still_owed` says who is left.
 
-To add a list, start from what the shop wants its ads to do. `list_audience_goals` returns four goals: `win_back` (bought, but not within `window_days`, which comes from the shop's kind of business), `stop_paying` (everyone who ever bought, left out of ads for new people), `interested` (added to cart or started checkout in the last 30 days and never bought; `locked` until those events arrive) and `lookalike` (everyone who bought, with what each spent, for a Meta value-based lookalike). Each says where its list can go now (`networks`) and which lists the shop already made for it (`lists`). If a goal already has a list, ask whether they want another rather than a copy. Tell the shop who goes and where, then call `add_audience` with the goal and `confirm: true`. Apex saves the goal's rule as a segment named after the list, so the shop can change who's on it in Segments, and sends the list right away unless `send_now: false`. The result's `sent` says how many people each platform took. Spend goes only to Meta: neither LinkedIn's nor Google's list upload takes it, so a list that carries spend reaches them as the same people without it. Say so rather than calling a Google or LinkedIn list value-based.
+To add a list, start from what the owner wants its ads to do. `list_audience_goals` returns four goals: `win_back` (bought, but not within `window_days`, which comes from the workspace's kind of business), `stop_paying` (everyone who ever bought, left out of ads for new people), `interested` (added to cart or started checkout in the last 30 days and never bought; `locked` until those events arrive) and `lookalike` (everyone who bought, with what each spent, for a Meta value-based lookalike). Each says where its list can go now (`networks`) and which lists the workspace already made for it (`lists`). If a goal already has a list, ask whether they want another rather than a copy. Tell the owner who goes and where, then call `add_audience` with the goal and `confirm: true`. Apex saves the goal's rule as a segment named after the list, so the owner can change who's on it in Segments, and sends the list right away unless `send_now: false`. The result's `sent` says how many people each platform took. Spend goes only to Meta: neither LinkedIn's nor Google's list upload takes it, so a list that carries spend reaches them as the same people without it. Say so rather than calling a Google or LinkedIn list value-based.
 
-Before sending one of the shop's own events (a trial start, a booked demo) to its ad platforms, call `preview_ad_platform_send` with the event name and what it means (`purchase`, `lead`, `signup`, `subscription`, `add_to_cart`, or `something_else`). Show the shop which platforms would hear it, under what name, and which can't and why, plus the `estimate`: how often it happened in the last 30 days and what a month of sends costs at the shop's price. It saves and sends nothing.
+Before sending one of the workspace's own events (a trial start, a booked demo) to its ad platforms, call `preview_ad_platform_send` with the event name and what it means (`purchase`, `lead`, `signup`, `subscription`, `add_to_cart`, or `something_else`). Show the owner which platforms would hear it, under what name, and which can't and why, plus the `estimate`: how often it happened in the last 30 days and what a month of sends costs at the workspace's price. It saves and sends nothing.
 
-When the shop says yes, call `add_ad_platform_send` with the same event and meaning and `confirm: true`. It saves the send on the shop's Conversion for that event, so experiments and goals count the same thing. If that Conversion already means something else, the tool is refused; change the meaning on Conversions first rather than picking a different meaning to get around it. For `something_else`, Apex makes the conversion on Meta itself so campaigns can optimize for it; if `couldnt_make` comes back, tell the shop Meta's reason (usually a reconnect). A platform showing `not_agreed` only hears it after the shop agrees on Attribution → Ad platforms; the tool never agrees for them. If `without_consent_answer` is `not_sent`, only events that carry a yes go out. `list_ad_platform_sends` shows what is being sent, and `remove_ad_platform_send` stops one and keeps the Conversion.
+When the owner says yes, call `add_ad_platform_send` with the same event and meaning and `confirm: true`. It saves the send on the workspace's Conversion for that event, so experiments and goals count the same thing. If that Conversion already means something else, the tool is refused; change the meaning on Conversions first rather than picking a different meaning to get around it. For `something_else`, Apex makes the conversion on Meta itself so campaigns can optimize for it; if `couldnt_make` comes back, tell the owner Meta's reason (usually a reconnect). A platform showing `not_agreed` only hears it after the owner agrees on Attribution → Ad platforms; the tool never agrees for them. If `without_consent_answer` is `not_sent`, only events that carry a yes go out. `list_ad_platform_sends` shows what is being sent, and `remove_ad_platform_send` stops one and keeps the Conversion.

package/skills/apex-journeys/SKILL.md

@@ -97,19 +97,19 @@ This is the canonical journey-skill workflow. **Always involve apex-communicatio
 The first install letter is a seeded template, not a journey to author from scratch. It starts on `app_install`, waits 24 hours, leaves the moment the person signs up, and sends one letter over push and email with an Apex Link back into the app.
 
 ```
-1. get_setup_state → the Mobile Measurement step "first-letter" says whether the shop can reach installers at all
+1. get_setup_state → the Mobile Measurement step "first-letter" says whether the workspace can reach installers at all
    (push keys or a verified sender). If neither: stop and send them to Set up Apex. publish_journey refuses
    a letter it cannot deliver; do not work around that.
 2. list_journeys → is a mobile-install-nudge journey already there? Turning it on twice sends two letters.
 3. create_journey_from_template({ template_id: "mobile-install-nudge" }) → a draft with the trigger, wait,
    exit and send already in place. Do not add_journey_step; review with get_journey.
 4. Reach is honest by construction: push goes to the device token, so an installer with no account still gets
-   it; email only goes to people the shop already knows. Say that — "everyone who installs gets the push;
+   it; email only goes to people the workspace already knows. Say that — "everyone who installs gets the push;
    only known people also get the email."
 5. publish_journey (after check_live_tests). Sends bill the communications meter.
 ```
 
-The setup step in the dashboard does steps 1–5 in one click with a reach preview; prefer sending the shop there when they are not in the editor.
+The setup step in the dashboard does steps 1–5 in one click with a reach preview; prefer sending the owner there when they are not in the editor.
 
 ### "Clean up journeys we don't use"
 

package/skills/apex-partner-network/SKILL.md

@@ -188,5 +188,5 @@ Policies:
 
 - `apex-integration-cookbook` — end-to-end patterns combining partner network + communications + experiments
 - MCP tools: `list_partner_programs`, `create_partner_program`, `invite_partner`, `approve_payouts`, `vouch_for_partner`, `get_effective_fees`
-- Stripe Connect for the shop is a hop: `start_integration_install` with `type: "stripe"`. Legal acknowledgements stay on the opened page.
+- Stripe Connect for the workspace is a hop: `start_integration_install` with `type: "stripe"`. Legal acknowledgements stay on the opened page.
 - Docs: `/docs/partner-network/` for concept walkthroughs + integration guides

package/skills/apex-setup/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: apex-setup
+description: Set up Apex in a repo from the editor. Sign in by browser approval, find or create the workspace this repo belongs to, name it, install and wire events, pick the conversion, work the Set up Apex checklist, stop for browser steps, and end on a first experiment or message. Use when someone says "set up Apex", "install Apex", "connect Apex", or runs /setup-apex.
+---
+
+# Set up Apex in this repo
+
+The owner should be looking at live data a few minutes after asking. They only open a browser when a person has to sign in, pay, or own a console or DNS.
+
+Three rules hold the whole way:
+
+- **No tool marks a step done.** Steps finish when the real thing happens: the name is saved, events arrive, the domain verifies. If a step looks stuck, the thing it waits on has not happened.
+- **The owner's "no" is theirs.** Record a skip or decline only after they say so, in their words.
+- **Every setup reply names the workspace it wrote to** (`workspace`). If it is not this repo's workspace, stop and switch before the next write.
+
+The same steps run as the `/setup-apex` prompt.
+
+## 1. Sign in
+Call get_setup_state. If Apex is not connected yet, the reply carries an approval link: show it, call wait_for_apex_approval, then carry on. Sign-in is browser approval only. Never ask for, paste, or save an API key to set up. If a reply starts with APEX_WAITING_FOR_ACCESS, say so in one sentence, give the link it names, and stop.
+
+## 2. Which workspace is this repo
+Read .apex/workspace.json. If it exists, switch_workspace to its workspace_key. If not, look for an Apex snippet or SDK workspace key in the code; that key is the workspace, and you write the file. If neither, ask the owner once: one of their workspaces (list_orgs shows them by organization), a new workspace in one of their organizations (create_workspace), or a separate company (create_organization). Ask "separate company, or another site of the same business?" before creating either. Write and commit the file. Every setup reply names the workspace it wrote to; if it is not this repo's workspace, stop and switch.
+
+## 3. Name the workspace from the repo
+If get_setup_state shows first-run incomplete, name the merchant before inventing events. Read the repo (package name, README, site config) and propose the organization name, workspace name, what the organization does, how people convert, and the website. Confirm with the owner, then save with update_organization and update_workspace. Set site_install to codebase when you install from this repo.
+
+## 4. Install and wire events
+Install the SDK or snippet the checklist names. Read get_event_spec before writing track calls, scan the code for what the site actually does, and report it with propose_wiring_plan. Wire those events. Do not invent event names to make a step look done. Then watch them arrive with apex_recent_events and get_wiring_status before moving on.
+
+## 5. Pick what counts as a conversion
+Ask the owner which event is the sale, signup, or lead that matters. Save it with create_conversion and set_primary_conversion.
+
+## 6. Work the checklist
+Call get_setup_state after every write and work the next step with the tool it names. When the owner says a step or area is not for them, record it with skip_setup_step or decline_setup_area, in their words. Never record one to make progress look finished. No tool marks a step done; steps finish when the real thing happens.
+
+## 7. Browser steps
+When the next step needs a person (payment, an ad or app store console, DNS, legal acknowledgements), give the link and the reason from the checklist and wait. Use start_integration_install for GitHub, Stripe, ad platforms, and Google Analytics; it polls until connected. After ads are connected, make a paid Apex Link before inventing UTMs.
+
+## 8. First value
+Once events are live, show the owner what arrived with apex_recent_events, and give them the live stream link it returns so they can watch their own site talk to Apex. Then propose exactly one first step from what you learned about the organization: one experiment with plan_experiment, or one message with recommend_communications. Say why it fits this workspace in a sentence. Create nothing live without the owner's yes; a draft they can open is fine.
+
+## Things that look done and are not
+
+- Name Production (and optional Beta) sites with `list_workspace_environments` / `set_workspace_environments` before you trust the Production numbers.
+- Consent answers (`set_consent_posture`) are not a tap on the live site. The owner still taps Allow there.
+- Sender-domain records issued are not verified. Poll `get_sender_domain` until it is.
+- Legal acknowledgements stay on the page `start_integration_install` opens. You cannot click the ad consoles or the DNS registrar for them.
+
+## The repo binding file
+
+`.apex/workspace.json` is committed with the repo:
+
+```json
+{
+  "workspace_key": "atlas-provisions-x1",
+  "workspace_name": "Atlas Provisions",
+  "org_name": "Acme Co"
+}
+```
+
+The workspace key is not a secret; it already ships in the site's snippet. One editor install serves every workspace the person can reach, and each repo's file decides which one it is. `create_workspace` and `create_organization` return this file's contents in `repo_binding`.
+
+## Example: two companies, one person
+
+Noah is signed in with his personal workspace. He opens his company's repo and says "set up Apex in this repo." There is no binding file and no snippet, so the agent asks which workspace. He picks "a separate company". The agent creates the "Acme Co" organization, switches to its workspace, writes `.apex/workspace.json`, and runs setup. Back in his personal repo, that repo's file sends the agent to his personal workspace with no question asked.
+
+## Keys are for servers
+
+An API key is for a server or CI job that cannot do browser approval (`/apex-keys`). Never put one in a committed file. Receipt keys and server keys go in the host's secret store.