@ia-qa/self-healing 1.6.6 → 1.6.7

package/README.md

@@ -16,7 +16,29 @@ One command. `ia-qa-heal run` runs your suite, watches it break, diffs the live
 
 *Real commands against a live site, real stdout — only the typing speed is synthesised.*
 
-## Quick start
+## Easiest start — have your agent set it up
+
+If you already work with Claude Code, Cursor, Copilot or another coding agent, don't configure this
+by hand. Paste this to it:
+
+```text
+Install and set up @ia-qa/self-healing in this project.
+1. First run `npx -y -p @ia-qa/self-healing ia-qa-heal skill --print` and follow it.
+   That output is the authoritative doc — do not guess any command or flag from memory.
+2. Register the MCP server so you can drive it yourself:
+   command `npx`, args ["-y", "-p", "@ia-qa/self-healing", "ia-qa-heal-mcp"].
+3. Read my e2e tests and my router, propose the page list for .ia-qa/config.json,
+   and wait for me to confirm before mapping anything.
+4. Then explain to me, in five lines: what map / baseline / diff / fix each do,
+   and which locators you will never rewrite without asking me.
+```
+
+Step 1 matters more than it looks: this package is newer than most models' training data, so an agent
+left to improvise will invent flags that don't exist. `skill --print` hands it the real instructions —
+including [the four prohibitions](#working-with-an-ai-agent--ia-qa-heal-skill) — before it touches
+anything. Step 4 is how you check it actually read them instead of guessing.
+
+## Quick start — by hand
 
 ```bash
 npx -y -p @ia-qa/self-healing ia-qa-heal init      # wizard → .ia-qa/config.json
@@ -37,7 +59,7 @@ npx ia-qa-heal init
 
 An agent that asks a browser where a button went is doing by hand what `.ia-qa/mapping/*.json` already answers offline: every interactive element's **role, accessible name and selector**, captured. A `link` the suite still calls a `button` shows up in one `grep`.
 
-`ia-qa-heal skill` installs that reflex — plus the rules that must not be broken — as a skill your agent loads:
+`ia-qa-heal skill` installs that reflex — plus the rules that must not be broken — as a skill your agent loads (this is what step 1 of the [paste-block above](#easiest-start--have-your-agent-set-it-up) makes it read):
 
 ```bash
 ia-qa-heal skill                 # where it would go, and whether it is current — writes nothing

package/TUTORIAL.md

@@ -83,7 +83,30 @@ Whatever it uses, it tells you: `Browser: system browser (channel "chrome")`.
 
 *Use this if you have Claude Code, Claude Desktop, Cursor, or another MCP-compatible agent. You'll talk to your app in plain English.*
 
-### Step 4.1 — Add the tool to your agent
+### Step 4.0 — The shortcut: let your agent do the whole setup
+
+The steps below are the manual version. If your agent can edit files in your project (Claude Code, Cursor, Copilot in your IDE), just paste this to it and skip straight to step 4.4 below:
+
+```text
+Install and set up @ia-qa/self-healing in this project.
+1. First run `npx -y -p @ia-qa/self-healing ia-qa-heal skill --print` and follow it.
+   That output is the authoritative doc — do not guess any command or flag from memory.
+2. Register the MCP server so you can drive it yourself:
+   command `npx`, args ["-y", "-p", "@ia-qa/self-healing", "ia-qa-heal-mcp"].
+3. Read my e2e tests and my router, propose the page list for .ia-qa/config.json,
+   and wait for me to confirm before mapping anything.
+4. Then explain to me, in five lines: what map / baseline / diff / fix each do,
+   and which locators you will never rewrite without asking me.
+```
+
+Two things to know about that prompt, because they are the difference between it working and it wasting your afternoon:
+
+- **Step 1 is not optional politeness.** This package is newer than most models' training data. An agent left to improvise invents flags that don't exist, they fail, and you conclude the tool is broken. `skill --print` hands it the real instructions — including the four things it must never do on its own — before it touches anything.
+- **Step 4 is your check.** If the five-line explanation is vague or mentions a verb that isn't `map`, `baseline`, `diff` or `fix`, it didn't read the skill. Tell it to run step 1 again.
+
+You will still have to **restart your agent** (step 4.2 below) after it writes the MCP config — it can't load a server it registered mid-conversation.
+
+### Step 4.1 — Add the tool to your agent (manual)
 
 Find your agent's MCP config file and add the `ia-qa-self-healing` block below.
 
@@ -134,6 +157,8 @@ Then point the config at the built file (use the **absolute** path):
 
 ### Step 4.1b — Teach your agent how to use it (recommended)
 
+*Skip this if you used step 4.0 — that prompt already made your agent do it.*
+
 The MCP block above gives your agent four *tools*. It does not give it the **judgment** to use them: when to read the contract instead of opening a browser, which verb answers which question, and — most importantly — which locators it must never rewrite on its own.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "description": "Local-first self-healing for UI tests: a local MCP server + CLI that map your app's pages to a role/name/selector contract, diff selector drift (PASS/FIX/BLOCK), and apply deterministic fixes to Cypress/Playwright/Selenium tests. Runs on your machine — nothing leaves it.",
   "keywords": [
     "self-healing",