@usercase/mcp 0.2.4-next.1 → 0.2.4-next.3

package/agents/condition.md

@@ -1,31 +1,31 @@
-A condition has a `page` (the screen the visitor is on when the card appears), `steps` in order, and a `moment`.
-
-Step kinds (`do`): `arrive` · `back` · `click` · `input` · `submit` · `scroll` · `idle` · `hide` (tab hidden) · `error` (a JavaScript error).
-Options on a step: `page`, `from` (arrive/back), `target` (click/input/submit), `atLeast`, `percent` (scroll), `seconds` (idle: a pause between two actions), `cleared` (input: typed then deleted), `absent` (this did not happen between the previous step and the moment).
-Moment: `on_match` (as soon as the steps are met) · `idle` with `seconds` (then that long with no action) · `leave` (about to leave; on phones, a long pause instead).
-
-Globs: `*` matches anything including `/`; `:name` matches one path segment (`/project/:slug`). Use the route parameter names from the code. Never put `?` or `#` in a glob.
-
-Targets match the element's own text, field name or class — case does not matter, and the words only need to be contained. Prefer the words the visitor saw. Use `class:name` for buttons without text and `tag:BUTTON` only when the text differs every time (a list of names).
-
-Steps happen in order, with anything allowed in between. All steps must happen; there is no "or" — two situations are two questions.
-
-**It cannot see:** what is on the screen (an error message, an empty list, a price), the values typed (only length and whether it was cleared), time limits ("within 10 seconds"), who the visitor is (device, new or returning, campaign), or anything across visits. A visit is one tab; 30 minutes of nothing starts a new one. If the user asks for one of these, say so and offer the nearest thing it can do — usually a behavior that goes with it (a submit followed by no arrival at the next page, instead of "an error was shown").
-
-Rules that make a card actually appear and mean something:
-- The card must be shown on the screen where the trouble is. A click that opens another page ends the situation — use the `arrive` on the next page instead.
-- Never ask while they are typing: the last step of an `on_match` condition must not be `input`. Use `idle` or the next step.
-- Never ask the moment someone lands on a sign-in, sign-up or payment screen; use `idle` or `leave` there.
-- The page must name a real screen, not only wildcards.
-- Narrow enough to be one situation: a condition that matches a large share of all visits is too broad.
-
-### Checking it
-
-Call `question_check` with the condition. Read the result:
-- **Problems**: fix them and check again. The server refuses the condition while there are any.
-- **Does not match recent visits** (matched 0, a path or word not seen): usually a wrong path or word — compare with `question_context` and the code, and fix it. But the screen or button may be new or not live yet. Then tell the user it has not been seen in recent visits, and send it with `acceptWarnings: true` only if they say so.
-- **Examples**: read what the matched visitors did. If it is not the situation the user meant, the condition is wrong even if it passes.
-- **Overlaps**: an existing question fires at the same moment; only one card shows per visit. Tell the user.
-- `idle` and `leave` moments are not counted by the check — it counts visits where the steps happened. Fewer people will actually see the card.
-
-`triggerEn`: one plain sentence a product manager understands, saying when the card appears. No paths or class names.
+A condition has a `page` (the screen the visitor is on when the card appears), `steps` in order, and a `moment`.
+
+Step kinds (`do`): `arrive` · `back` · `click` · `input` · `submit` · `scroll` · `idle` · `hide` (tab hidden) · `error` (a JavaScript error).
+Options on a step: `page`, `from` (arrive/back), `target` (click/input/submit), `atLeast`, `percent` (scroll), `seconds` (idle: a pause between two actions), `cleared` (input: typed then deleted), `absent` (this did not happen between the previous step and the moment).
+Moment: `on_match` (as soon as the steps are met) · `idle` with `seconds` (then that long with no click, typing or page change; scrolling and reading still count as a pause) · `leave` (about to leave; on phones, a long pause instead).
+
+Globs: `*` matches anything including `/`; `:name` matches one path segment (`/project/:slug`). Use the route parameter names from the code. Never put `?` or `#` in a glob.
+
+Targets match the element's own text, field name or class — case does not matter, and the words only need to be contained. Prefer the words the visitor saw. Use `class:name` for buttons without text and `tag:BUTTON` only when the text differs every time (a list of names).
+
+Steps happen in order, with anything allowed in between. All steps must happen; there is no "or" — two situations are two questions.
+
+**It cannot see:** what is on the screen (an error message, an empty list, a price), the values typed (only length and whether it was cleared), time limits ("within 10 seconds"), who the visitor is (device, new or returning, campaign), or anything across visits. A visit is one tab; 30 minutes of nothing starts a new one. If the user asks for one of these, say so and offer the nearest thing it can do — usually a behavior that goes with it (a submit followed by no arrival at the next page, instead of "an error was shown").
+
+Rules that make a card actually appear and mean something:
+- The card must be shown on the screen where the trouble is. A click that opens another page ends the situation — use the `arrive` on the next page instead.
+- Never ask while they are typing: the last step of an `on_match` condition must not be `input`. Use `idle` or the next step.
+- Never ask the moment someone lands on a sign-in, sign-up or payment screen; use `idle` or `leave` there.
+- The page must name a real screen, not only wildcards.
+- Narrow enough to be one situation: a condition that matches a large share of all visits is too broad.
+
+### Checking it
+
+Call `question_check` with the condition. Read the result:
+- **Problems**: fix them and check again. The server refuses the condition while there are any.
+- **Does not match recent visits** (matched 0, a path or word not seen): usually a wrong path or word — compare with `question_context` and the code, and fix it. But the screen or button may be new or not live yet. Then tell the user it has not been seen in recent visits, and send it with `acceptWarnings: true` only if they say so.
+- **Examples**: read what the matched visitors did. If it is not the situation the user meant, the condition is wrong even if it passes.
+- **Overlaps**: an existing question fires at the same moment; only one card shows per visit. Tell the user.
+- `idle` and `leave` moments are not counted by the check — it counts visits where the steps happened. Fewer people will actually see the card.
+
+`triggerEn`: one plain sentence a product manager understands, saying when the card appears. No paths or class names.

package/agents/steps.md

@@ -31,7 +31,11 @@ Use their word for the card: a question when it is a question, an invite when it
 Make sure the moment fits the card:
 
 - **A question** appears when the visitor can answer it, right where the thing it asks about happened.
-- **A research invite** asks for a few minutes of someone's time. It should reach the people the research is about — visitors who just went through the part of the site it covers — at a moment when they are free to say yes: after they finished or stopped doing something, or as they are about to leave. Never in the middle of typing, paying or signing in.
+- **A research invite** asks for a few minutes of someone's time. It should reach the people the research is about — visitors who just went through the part of the site it covers — at a moment when they are free to say yes: right after they finished the action the research is about (`on_match` on that step), or as they are about to leave (`leave`). Do not wait for a long pause after the action; people keep scrolling and moving on, so such an invite rarely appears. Never in the middle of typing, paying or signing in.
+
+When a research invite fires at the same moment as a live question, that is expected, not a conflict. A visitor sees only one card at a time and the question comes first; anyone who answers it is offered the research right after, in the same card, and the invite card reaches the visitors the question no longer reaches. Mention the overlap as information only. Never suggest turning a question off to make room for an invite.
+
+When you list overlapping questions, quote each one exactly as the check returned it and say which moment it shares; do not refer to them by position.
 
 ## 4. Send it back
 

package/mcp/server.js

@@ -329,7 +329,7 @@ const QCondition = z.object({
   page: z.string().describe("Path glob of the screen the visitor is on when the question appears"),
   steps: z.array(QStep).describe("What happened, in order. Other actions may happen in between"),
   moment: z.object({
-    type: z.enum(["on_match", "idle", "leave"]).describe("on_match = as soon as the steps are met · idle = after that, N seconds with no action · leave = when about to leave"),
+    type: z.enum(["on_match", "idle", "leave"]).describe("on_match = as soon as the steps are met · idle = after that, N seconds with no click, typing or page change (scrolling still counts as a pause) · leave = when about to leave"),
     seconds: z.number().optional(),
   }),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.4-next.1",
+  "version": "0.2.4-next.3",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",