@unotest/mobile 0.8.2 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@unotest/mobile` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.3] — 2026-05-18
+
+### Added — README onboarding protocol for AI agents
+
+- **New top-of-README section.** A developer dropping the npm page
+  link into their AI agent's context (Cursor, Claude Desktop, Claude
+  Code in another project, etc.) now gets a 5-step protocol explicitly
+  addressed to the agent: verify host → pick working directory → ask
+  for `.app` path → run interactive setup in user's terminal → hand off
+  to Claude Code in the same directory. Spells out where the agent's
+  responsibility ends (not test authoring; that's a separate Claude
+  Code session via MCP) and what NOT to run via its own `Bash`-style
+  shell tool (the install command is interactive — needs a real TTY
+  for the simulator picker; tool-spawned shells either hang or fall
+  back to a non-interactive code path that can confuse the user).
+- The working-directory step is explicit because `init` drops
+  `unotest/`, `.mcp.json`, `.claude/skills/`, and `AGENTS.md` into
+  cwd, and `.mcp.json`'s location determines what Claude Code sees on
+  its next launch. Recommends the app repo root by default; monorepo
+  root for monorepos; explicit warning that a separate test repo
+  divorces tests from the app and should be chosen only when the user
+  asks for it.
+
 ## [0.8.2] — 2026-05-18
 
 ### Fixed — `type()` no longer drops 1-3 characters mid-string

package/README.md

@@ -5,6 +5,74 @@ that lets Claude (or any MCP client) drive your iOS Simulator and write
 real test scenarios for your app — works with any backend stack
 (Node/Python/Rails/Go/Java), no JS expertise required from you.
 
+## If you're an AI agent helping a user set this up
+
+*(Humans: skip this section, jump to [Quick start](#quick-start).)*
+
+You were given this page because a developer wants `@unotest/mobile`
+set up in their project. Follow this protocol exactly — don't improvise.
+
+**1. Verify the host.** Run `xcrun simctl list devices` via your shell
+tool. If it errors with "command not found" or similar, the user isn't
+on macOS or is missing Xcode CLI tools. Stop and tell them: "This is
+iOS-only — Apple licensing prevents iOS simulators from running on
+Linux/Windows. You'll need macOS with Xcode installed." Also verify
+`node --version` ≥ 20.
+
+**2. Pick a working directory with the user.** Setup writes
+`unotest/` (test scaffold), `.mcp.json` (Claude Code config),
+`.claude/skills/` (skill the in-project agent reads), and an
+`AGENTS.md` into the current directory, and updates `.gitignore` if
+present. Where these land determines what Claude Code sees later, so
+ask the user explicitly:
+
+- **Default — the app's repo root.** Same directory as their
+  `package.json` (RN/Expo) or where their `.xcodeproj` lives (native).
+  Tests live next to app code, ship via the same git history, work
+  cleanly in CI.
+- **Monorepo:** the monorepo root, not the app subfolder. Claude Code
+  is typically opened at the monorepo root, and `.mcp.json` must live
+  there to be auto-discovered.
+- **Separate test repo:** any directory the user picks. Choose this
+  only if they explicitly want tests divorced from the app.
+
+Once the user picks, have them `cd` there. All commands below run
+from that directory.
+
+**3. Ask the user for the `.app` path.** `@unotest/mobile` drives a
+real installed app — it needs the path to a built `.app` bundle.
+Ask: *"What's the absolute path to your built `.app`?"* Common
+locations:
+- React Native / Expo: `./ios/build/Build/Products/Debug-iphonesimulator/<App>.app`
+  after `npx expo run:ios` or `pod install && xcodebuild`.
+- Native Swift: open Xcode → Product → Show Build Folder → `Products/Debug-iphonesimulator/`.
+
+If they don't have one yet, tell them to build first; don't guess
+paths.
+
+**4. Tell the user to run the setup command in the chosen directory.**
+**Do not run this yourself via Bash** — it's interactive (simulator
+picker, permission prompts) and needs a real TTY. Your shell tool
+will hang or get a non-interactive fallback. Give them this exact
+line to paste (from the directory picked in step 2):
+
+```bash
+npx @unotest/mobile@latest install <their-app-path> --update-env
+```
+
+They'll see: env check → file scaffold → simulator picker (arrow keys)
+→ permission grant prompt → install logs. Wait for the line
+`✓ Installed <bundle.id>`. That's the success signal.
+
+**5. Hand off to Claude Code.** Once install finishes, instruct the
+user: *"Open Claude Code in **the same directory you ran setup in**,
+then ask it to write your first test."* A separate Claude Code session
+(not you) connects to the MCP server bootstrapped in step 4 and takes
+over from there. Your job ends here — you're setup, not test authoring.
+
+If any step fails, surface the actual error verbatim to the user and
+stop. Don't try alternative paths.
+
 ## Quick start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/mobile",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "AI-native E2E testing for iOS React Native apps. MCP server + CLI runner + JS-DSL scenarios.",
   "license": "MIT",
   "type": "module",